一、引言
随着前端技术快速发展，需求往往需要在多端（原生 Android/iOS、H5 网站、微信/支付宝/百度小程序等）同时发布，而维护多套代码成本极高。uniapp 作为 DCloud 出品的跨端框架，能够用一套 Vue 风格的源码，通过 HBuilderX 或 CLI，一次编写、编译到多个运行环境，大幅度提高开发效率。本文将从项目搭建→编码调试→平台特性→打包构建→发布上线等环节，逐步讲解如何完成一个跨 iOS、Android、Web 与各类小程序的完整 uniapp 项目。
全篇内容包括：
- 项目环境准备与基础搭建
- uniapp 项目结构与核心配置解析
- 页面示例与跨端差异处理（#ifdef 条件编译）
- H5（Web）端开发与发布
- 微信/支付宝/百度小程序端开发与发布
- 原生 App（iOS/Android）端开发与发布
- 多端资源管理与性能优化
- 完整流程图解与常见问题
通过示例代码和 ASCII 图解，你将对 uniapp 的跨多端原理与实操流程有全面而深入的了解，能够在项目中快速上手并发布到各个平台。
二、项目环境准备与基础搭建
2.1 环境依赖
HBuilderX 或 CLI
- 推荐使用最新版本的 HBuilderX（≥ v3.0），它集成了 uniapp 可视化项目创建、编译、真机调试、打包发布等功能。
- 如果偏好命令行，也可使用 Vue CLI +
@dcloudio/vue-cli-plugin-uni搭建。本文以 HBuilderX 为主，另附 CLI 方式要点。
Node.js & Git
- 安装 Node.js（≥ v10），用于部分插件与脚本。
- 安装 Git，方便版本控制和模板初始化。
目标平台开发环境
- 微信小程序：微信开发者工具。
- 支付宝小程序：支付宝小程序开发者工具。
- 百度小程序：百度小程序开发者工具。
- iOS：macOS + Xcode（用于打包 IPA）。
- Android：Android Studio（用于打包 APK）。
- H5：任意支持 HTTPS 的 Web 服务器（可用本地
npm run serve或使用 Nginx、GitHub Pages 等发布）。
2.2 创建 uniapp 项目
2.2.1 HBuilderX 可视化创建
- 打开 HBuilderX，选择 “文件→新建→项目→uni-app”，填写项目名称（如
uni-multi-platform-demo），选择空白模板。 - 创建后，会得到一个包含
pages.json、manifest.json、App.vue、main.js等文件的目录结构（见下节详解）。 - 在 HBuilderX 左侧选中项目根目录，点击工具栏**“运行”**按钮，可以选择“运行到浏览器-Chrome”查看 H5，也可“运行到小程序-微信”预览微信小程序效果。
2.2.2 CLI 创建（可选）
# 全局安装 @vue/cli（如未安装）
npm install -g @vue/cli
# 创建uniapp项目
vue create -p dcloudio/uni-preset-vue uni-multi-platform-demo
# 进入项目
cd uni-multi-platform-demo
# 运行 H5（本地预览）
npm run dev:%PLATFORM% # 例如 npm run dev:h5
# 生成各端代码
npm run build:%PLATFORM% # 如 build:mp-weixin、build:app-plus 等注：CLI 方式仅需在package.json中配置好脚本，使用npm run dev:h5、npm run build:mp-weixin即可。本文示例主要基于 HBuilderX，CLI 方式可参考官方文档。
三、uniapp 项目结构与核心配置解析
创建完成后，项目结构大致如下（以 HBuilderX 默认空白模板为例）：
uni-multi-platform-demo/
├─ components/ # 可存放自定义组件
├─ pages/ # 页面目录（每个子文件夹为一个页面）
│ ├─ index/
│ │ ├─ index.vue
│ │ └─ index.json # 页面配置（部分情况下需要）
│ └─ about/
│ ├─ about.vue
│ └─ about.json
├─ static/ # 静态资源：图片、字体、视频等
│ └─ logo.png
├─ unpackage/ # 编译后生成的各端临时文件。不要在此目录下修改源代码！
├─ App.vue # 全局 Vue 根组件
├─ main.js # 入口 JS（初始化小程序/APP）
├─ pages.json # 页面路由 & 导航栏 & 组件等全局配置
├─ manifest.json # 应用发布打包配置（APP 端配置）
└─ manifest.*.json # 若使用多渠包，可有多个 platform 相应配置
└─ pays.drawjson # 云打包平台等相关配置（可忽略）3.1 pages.json 详解
pages.json 是 uniapp 的路由 & 页面配置总入口，它决定了最终项目的页面路径、导航栏标题、分享设置、底部 TabBar 等。典型示例：
// pages.json
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页"
}
},
{
"path": "pages/about/about",
"style": {
"navigationBarTitleText": "关于"
}
}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "uni-app",
"navigationBarBackgroundColor": "#FFFFFF",
"backgroundColor": "#F2F3F5"
},
"tabBar": {
"color": "#7A7E83",
"selectedColor": "#007AFF",
"backgroundColor": "#ffffff",
"borderStyle": "black",
"list": [
{
"pagePath": "pages/index/index",
"iconPath": "static/icons/home.png",
"selectedIconPath": "static/icons/home-selected.png",
"text": "首页"
},
{
"pagePath": "pages/about/about",
"iconPath": "static/icons/about.png",
"selectedIconPath": "static/icons/about-selected.png",
"text": "关于"
}
]
}
}pages：页面数组，顺序决定小程序/APP 端页面栈的顺序与路由顺序；每个对象path对应某个页面文件夹（如pages/index/index.vue）。globalStyle：定义全局导航栏与背景色等属性，可覆盖各端原生默认样式。tabBar：若需要底部 Tab 栏，则在此配置图标、文字与对应pagePath。在 H5 端会渲染为自定义 Tab，而在小程序/APP 端会渲染原生 Tab（或仿 Tab）。
注意：小程序端页面的路径不能超过 10 层；路径中不要出现大小写冲突，否则会导致编译错误或真机奔溃。
3.2 manifest.json 与原生打包配置
manifest.json 是针对 APP（iOS/Android）打包的配置文件，主要包含应用名称、AppID、版本号、图标、权限设置、SDK 集成等信息。HBuilderX 可视化界面会自动同步修改此文件。示例（精简版）：
// manifest.json
{
"name": "uni-multi-platform-demo",
"appid": "__UNI__XXXXXXXX",
"versionName": "1.0.0",
"versionCode": "100",
"description": "一个 uniapp 跨多端示例项目",
"h5": {
"title": "uniapp 多端示例",
"routerMode": "hash",
"devServerPort": 8080,
"favicon": "static/logo.png"
},
"app-plus": {
"distribute": {
"android": {
"package": "com.example.unimultiplatform",
"keystorePath": "build/keystore/your.keystore",
"keystorePassword": "your_keystore_password",
"alias": "your_alias",
"aliasPassword": "your_alias_password"
},
"ios": {
"codeSign": {
"developmentTeam": "YOUR_TEAM_ID",
"provisioningProfile": "build/provisioning/your_mobileprovision",
"codeSignIdentity": "iPhone Distribution: Your Company (TEAMID)"
}
}
},
"sdkConfigs": {
"WXSDK": {
"appId": "wxxxxxxxxxxxxxxxx",
"universalLink": "https://xxxxxx.com/"
}
}
}
}name/appid：APP 应用名称与 HBuilderX 分配的uni-appAppID；versionName/versionCode：iOS/Android 端的版本号与版本代码；h5：H5 端的标题、routerMode（hash或history）以及开发服务器端口等；app-plus.distribute.android：Android 打包参数，包括包名（package）、签名文件路径与密码等；app-plus.distribute.ios：iOS 打包参数，包括开发团队 ID、描述文件（.mobileprovision）以及签名证书标识；app-plus.sdkConfigs：可配置集成第三方 SDK（如微信登录、统计、推送等），上例演示了微信原生 SDK 的appId与universalLink。
注意：
- Android 端打包时，
keystore文件需自行在本地生成并配置正确路径；- iOS 端打包需在 macOS 上使用 Xcode 证书管理工具，获取
DevelopmentTeam、Provisioning Profile与CodeSignIdentity；- H5 端通过
manifest.json配置的h5.routerMode影响页面路径的 URL 形式（hash推荐跨域兼容性更好）；- 各平台的
manifest.json节点名以app-plus开头，HBuilderX 打包时会读取并生成对应平台项目文件。
四、页面示例与跨端差异处理
4.1 简单页面示例：pages/index/index.vue
下面给出一个包含入口按钮、分享按钮与跳转示例的页面，演示跨端差异处理：
<template>
<view class="page-container">
<text class="title">uniapp 多端开发示例</text>
<button @click="goToAbout">跳转到关于页</button>
<!-- 跨端分享按钮 -->
<button @click="onShareButton">统一分享</button>
<!-- 仅在 APP 端显示 -->
<button v-if="platform === 'app-plus'" @click="onAppOnlyAction">
仅 APP 端执行
</button>
<!-- 仅在小程序端显示 -->
<button v-if="isMp" open-type="share">分享到小程序</button>
<!-- 仅在 H5/公众号端显示 -->
<button v-if="platform.startsWith('h5')" @click="onWebOnlyAction">
仅 H5 端执行
</button>
</view>
</template>
<script>
// 引入平台检测与分享工具
import { getPlatform } from '@/utils/platform';
import { shareHandler } from '@/utils/share';
export default {
data() {
return {
platform: getPlatform()
};
},
computed: {
isMp() {
return this.platform.startsWith('mp-');
}
},
methods: {
goToAbout() {
uni.navigateTo({ url: '/pages/about/about' });
},
onShareButton() {
const shareConfig = {
title: 'uniapp 跨多端示例',
desc: '覆盖 iOS、Android、Web、小程序 全端',
link: 'https://example.com/h5/share.html',
imgUrl: 'https://example.com/static/thumb.png',
path: '/pages/index/index?from=mini',
miniProgram: {
id: 'gh_abcdefg',
path: '/pages/index/index',
type: 0
}
};
shareHandler(shareConfig);
},
onAppOnlyAction() {
uni.showToast({ title: '仅在 APP 端执行', icon: 'none' });
},
onWebOnlyAction() {
alert('仅在 H5 端执行');
}
}
};
</script>
<style scoped>
.page-container {
display: flex;
flex-direction: column;
align-items: center;
padding: 50px;
}
.title {
font-size: 24px;
margin-bottom: 30px;
}
button {
margin: 10px 0;
padding: 10px 20px;
font-size: 16px;
}
</style>说明：
getPlatform()返回当前端标识，通过v-if条件渲染让某些按钮只在特定端显示；- 小程序端分享按钮需使用
open-type="share"才能触发onShareAppMessage；- H5 端
onWebOnlyAction演示alert弹窗；APP 端onAppOnlyAction演示uni.showToast；- “统一分享”按钮调用封装好的
shareHandler()，不同端会执行不同分享逻辑。
4.2 条件编译示例（#ifdef / #ifndef）
在 uniapp 中，可以使用如下条件编译指令进行更细粒度的端内分支：
<template>
<view>
<!-- 仅在 APP 端显示 -->
<!-- #ifdef APP-PLUS -->
<text>仅 APP 端可见</text>
<!-- #endif -->
<!-- 仅在微信小程序端显示 -->
<!-- #ifdef MP-WEIXIN -->
<text>仅微信小程序端可见</text>
<!-- #endif -->
<!-- 仅在 H5 端显示 -->
<!-- #ifdef H5 -->
<text>仅 H5 端可见</text>
<!-- #endif -->
<!-- 仅在非 APP 端显示 -->
<!-- #ifndef APP-PLUS -->
<text>非 APP 端可见</text>
<!-- #endif -->
</view>
</template>使用条件编译可以将不需要打包到某端的代码块彻底剔除，减少包体积。例如，将“仅 H5 端”的依赖放在 #ifdef H5 中，在小程序/APP 打包时不会包含这些代码。
五、H5（Web）端开发与发布
5.1 H5 端路由与打包
uniapp H5 端生成的是一套纯前端网页，页面路由默认采用hash 模式（在 manifest.json 中可切换为 history）。编译后会在项目根目录生成 unpackage/dist/build/h5/ 文件夹，其中包含 index.html、static、favicon.ico 等文件。
5.1.1 H5 本地预览
在 HBuilderX 中选择“运行→运行到浏览器-Chrome”，即可自动启动本地 localhost 服务（默认端口 8080）预览 H5 端效果；也可以在命令行中执行：
npm run dev:h5然后在浏览器访问 http://localhost:8080/#/pages/index/index 即可看到效果。
5.1.2 H5 打包上线
- 在 HBuilderX 左侧项目根目录，点击“发行→网站-H5→发行”或在命令行执行
npm run build:h5； - 打包完成后，生成的
dist/build/h5/目录下的文件即为可部署静态资源； - 将
dist/build/h5/*上传到任意支持 HTTPS 的服务器（如 Nginx、Apache、GitHub Pages、Netlify、Vercel 等），即可通过域名访问。 - 若你在
manifest.json中设置了routerMode: 'history'，则需在服务器端做404 回退到index.html，以便前端路由正常工作；若使用hash，则无需额外配置。
ASCII 图解：H5 部署流程
+---------------------------------------+ | uniapp 项目根目录 | | ┌───────────────────────────────────┐ | | │ 运行：npm run build:h5 │ | | │ ───────────────────────────────── │ | | │ 生成 dist/build/h5/ 目录 │ | | └───────────────────────────────────┘ | | ↓ | | 上传 dist/build/h5/* 到服务器 | | ↓ | | 域名指向 → 浏览器访问 https://… | +---------------------------------------+
5.2 H5 端常见优化
打包体积：在
vue.config.js或manifest.json中关闭 SourceMap、开启压缩、提取公共包：// vue.config.js (如果使用 CLI) module.exports = { productionSourceMap: false, configureWebpack: { optimization: { splitChunks: { chunks: 'all' } } } };- PWA 与离线缓存：可利用 Workbox 将 H5 端打包为 PWA，支持离线访问和缓存策略，但一般小程序/APP 端已打包，不必过度依赖 PWA。
- 环境变量：在 H5 端可通过
process.env.NODE_ENV判断生产/开发环境，进行不同配置。例如 API 接口地址，C端调用可使用uni.request。
六、小程序端开发与发布（微信/支付宝/百度）
6.1 微信小程序开发与发布
6.1.1 本地预览与调试
- 在 HBuilderX 中点击“运行→运行到小程序模拟器-微信”，自动打开微信开发者工具；也可在命令行执行
npm run dev:mp-weixin。 - 在微信开发者工具里，可以看到
miniprogram_dist/build/mp-weixin/目录下的源码，方便进行真机预览与调试。
6.1.2 发布到微信小程序
- 小程序账号准备：确保你有一个已注册且已认证的微信小程序账号，并获得 AppID；
HBuilderX 打包：在 HBuilderX 中点击“发行→小程序-微信”，输入 AppID，选择“云打包”或“本地打包”；
- 本地打包：生成原生小程序项目，路径为
unpackage/dist/build/mp-weixin/，然后在微信开发者工具手动导入该项目并上传； - 云打包：填写 AppID、版本号、版本描述后，一键提交给 DCloud 云打包平台，生成可直接提交审核的小程序代码。
- 本地打包：生成原生小程序项目，路径为
- 微信开发者工具上传审核：若本地打包，打开“微信开发者工具”，点击“上传”，填写版本号、描述等，提交审核。
- 审核通过后发布：在微信公众平台后台，审核通过后可选择发布上线。
ASCII 图解：微信小程序打包流程
uniapp 源码 ↓ (HBuilderX “发行→小程序-微信”) unpackage/dist/build/mp-weixin/ (已生成微信小程序项目) ↓ (导入到微信开发者工具) 微信开发者工具 → 上传 → 审核 → 发布上线
6.1.3 小程序端注意事项
- 页面数量限制：微信小程序最多 50 个页面；页面路径不能超过 10 层；
- 接口限额：注意
uni.request等网络请求不要滥用，合理缓存或限流； - 分享逻辑：需在页面内实现
onShareAppMessage/onShareTimeline； - 分包与分隔加载：当小程序体积过大时，可在
pages.json中配置subPackages，拆分页面分包加载，首包控制在 2MB 以内。
6.2 支付宝小程序开发与发布
6.2.1 本地预览与调试
- 在 HBuilderX 中点击“运行→运行到小程序模拟器-支付宝”，自动打开支付宝小程序开发者工具；或命令行执行
npm run dev:mp-alipay。 unpackage/dist/build/mp-alipay/下的目录即为支付宝小程序源代码，可在工具中预览与调试。
6.2.2 发布到支付宝小程序
- 账号准备：拥有支付宝小程序账号与 AppID；
- HBuilderX 打包：点击“发行→小程序-支付宝”，输入 AppID，选择“本地打包”或“云打包”；
- 支付宝开发者工具上传：若本地打包，将
unpackage/dist/build/mp-alipay/导入工具，填写版本信息后上传； - 审核与上线：在支付宝小程序管理后台提交审核，审核通过后即可发布。
提示：支付宝小程序对代码量要求严格，最终包体大小应控制在 2MB 左右，若超限需开启“分包”。
6.3 百度小程序开发与发布
6.3.1 本地预览与调试
- 在 HBuilderX 中点击“运行→运行到小程序模拟器-百度”或命令行执行
npm run dev:mp-baidu； unpackage/dist/build/mp-baidu/下文件即为百度小程序项目，可在百度开发者工具中预览。
6.3.2 发布到百度小程序
- 账号准备：拥有百度智能小程序账号与 AppID；
- HBuilderX 打包：点击“发行→小程序-百度”，输入 AppID，选择“本地打包”或“云打包”；
- 百度开发者工具上传：将生成的项目导入百度开发者工具，填写版本、提交审核；
- 审核与上线：审核通过后发布。
注意：百度小程序和微信小程序类似，也有页面数量与体积限制，需分包分离。
七、原生 App（iOS/Android）端开发与发布
7.1 APP 端流程图解
uniapp 源码
↓ (HBuilderX “发行→原生 App-云打包 / 本地打包”)
unpackage/dist/build/app/ (iOS Xcode 项目 或 Android Gradle 项目)
↓ (Xcode / Android Studio 打开项目)
↓ (生成 IPA / APK)
↓ (上传 App Store / 上架 Google Play / 内部测试)7.2 Android 端打包与发布
7.2.1 生成签名文件（Keystore）
# 在命令行生成 .keystore，例如：
keytool -genkey -v -keystore yourapp.keystore \
-alias your_alias \
-keyalg RSA -keysize 2048 -validity 10000
# 过程中会提示输入 keystore 密码、别名密码、姓名、组织等将生成的 yourapp.keystore 放到项目中，例如放在 build/keystore/yourapp.keystore，并在 manifest.json 中配置好：
"app-plus": {
"distribute": {
"android": {
"package": "com.example.uniplatformdemo",
"keystorePath": "build/keystore/yourapp.keystore",
"keystorePassword": "keystore_password",
"alias": "your_alias",
"aliasPassword": "alias_password"
}
}
}7.2.2 本地打包 Android
- 在 HBuilderX 中，选择“发行→原生 App-本地打包”，选择 Android 平台；
- 填写包名、版本号、签名信息（已在
manifest.json中配置，可直接勾选）； - 点击“打包”，HBuilderX 会生成一个
*.apk文件（存放在unpackage/dist/build/app/**/*.apk）； 用真机或模拟器安装测试：
adb install -r unpackage/dist/build/app/android/xxx.apk- 测试无误后，将 APK 上传到 Google Play、华为应用市场、应用宝等第三方应用商店。
7.2.3 云打包 Android
- 在 HBuilderX 中勾选 “云打包”，填写应用名称、版本号、签名信息等；
- 提交打包，等待完成后在“云打包”记录中下载 APK；
- 测试并上传到各大应用商店。
注意：
- Gradle 构建时可能出现依赖冲突，可在 HBuilderX “项目设置→插件管理”中查看使用的插件版本；
- 如果需要集成第三方原生 SDK（如推送、统计、地图等），可在项目
components/plugins中复制对应.aar/.jar文件，并修改 Android 工程配置（可参考文档或示例）；- Android 端需要关注权限声明（在
manifest.json中配置），例如相机、定位等，打包时会生成原生 AndroidManifest.xml。
7.3 iOS 端打包与发布
7.3.1 准备证书与描述文件
- Apple 开发者账号：登录 Apple Developer 网站，创建一个 App ID 并开启所需功能（推送、健康、定位等）；
- 创建证书：在 “Certificates, IDs & Profiles” 中创建 iOS Development 证书 与 iOS Distribution 证书，并下载到本地；双击安装到 macOS 钥匙串中；
- 创建描述文件：分别创建 Development Provisioning Profile（野狗调试） 和 Distribution Provisioning Profile（App Store 上架）；将
.mobileprovision文件下载到本地。
7.3.2 本地打包 iOS
在
manifest.json中填入："app-plus": { "distribute": { "ios": { "codeSign": { "developmentTeam": "YOUR_TEAM_ID", "provisioningProfile": "build/provisioning/your.mobileprovision", "codeSignIdentity": "iPhone Distribution: Your Company (YOUR_TEAM_ID)" } } } }developmentTeam为 Apple 开发者账号中的 Team ID；provisioningProfile填写本地.mobileprovision文件路径；codeSignIdentity与证书名称保持一致。
- 在 HBuilderX 中，选择“发行→原生 App-本地打包”，选择 iOS 平台；输入 Bundle Identifier（与 App ID 一致），选择签名证书与描述文件；
- 点击“打包”，HBuilderX 会生成一个
.ipa文件，存放在unpackage/dist/build/app/ios/下； - 使用 Application Loader（或 Xcode → Organizer）上传
.ipa至 App Store Connect；或使用 TestFlight 发布测试。
7.3.3 云打包 iOS
- 在 HBuilderX 中勾选**“云打包”**，填写证书内容（点击导入
.p12证书、描述文件.mobileprovision），填写 Bundle ID、版本号、版本描述等； - 提交打包，等待完成后下载
.ipa； - 上传到 App Store Connect，或使用第三方分发平台（蒲公英、Fir 等）进行测试分发。
注意：
- iOS 端打包只能在 macOS 上完成；云打包平台代替本地 Xcode 编译；
- 由于 Apple 政策限制，想要集成第三方原生 iOS SDK，需要在 HBuilderX “发行插件”中配置或借助原生插件；
八、多端资源管理与性能优化
8.1 静态资源（图片、字体、音视频）
放在
static/目录：static下的所有文件会原样复制到打包产物根目录；H5 引用路径为/static/xxx.png；小程序端引用路径为/static/xxx.png；APP 端可用"/static/xxx.png"或"../../../static/xxx.png"。
按需加载：
- 对于 H5 端可使用
lazy-load、CDN 加速；小程序端可使用<image lazy-load />实现图片懒加载。
- 对于 H5 端可使用
尺寸与压缩：
- 推荐 SVG 或WebP 格式降低体积；对 PNG/JPG 进行压缩；确保 APP 端 APK/IPA 体积不过大。
8.2 条件编译处理资源
如果某些资源仅在特定端有效，可用条件编译提前剔除。例如：
<template>
<view>
<!-- #ifndef H5 -->
<image src="@/static/native-only.png" />
<!-- #endif -->
<!-- #ifdef H5 -->
<image src="/static/web-only.jpg" />
<!-- #endif -->
</view>
</template>这样，编译到 H5 时会移除 native-only.png 引用，减小包体积；编译到 APP/小程序 时会移除 web-only.jpg。
8.3 性能优化技巧
减少首次渲染体积：
- 在 H5 端，通过
vue.config.js拆分代码（splitChunks）； - 在小程序/APP 端，通过分包（小程序端）和按需编译（APP 端）。
- 在 H5 端，通过
合理使用缓存：
- H5 端可结合 Service Worker 离线缓存；小程序端可使用
uni.setStorage缓存接口返回数据；APP 端可使用 SQLite 或原生缓存。
- H5 端可结合 Service Worker 离线缓存；小程序端可使用
事件与定时器释放：
- 在 uniapp 页面
onUnload中清理setInterval、uni.$on事件监听等，避免内存泄漏。
- 在 uniapp 页面
图片切片与懒加载：
- 对大型列表使用虚拟列表组件（如
uni-virtual-list）；对长图、视频等做懒加载/骨架屏。
- 对大型列表使用虚拟列表组件（如
九、完整流程图解与常见问题
以下用 ASCII 图解串联起 uniapp 跨多端的整体流程，帮助你理清思路。
┌────────────────────────────────┐
│ 1. 项目初始化 │
│ HBuilderX（或 CLI）→ 新建 uniapp 项目 │
└────────────────────────────────┘
↓
┌───────────────────────────────────────────────┐
│ 2. 编写业务代码 & 跨端差异处理 │
│ - pages.json 配置页面路由/导航/TabBar │
│ - manifest.json 配置 APP 端包名/签名/SDK │
│ - 页面使用 #ifdef 做端内逻辑分支 │
│ - 通过 uni.request、uni.navigateTo 等 API │
│ - 资源放置在 static 目录，条件编译剔除不必要资源 │
└───────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────┐
│ 3. 本地预览与调试 │
│ - H5 端：运行至浏览器（npm run dev:h5） │
│ - Weixin：运行至微信开发者工具（npm run dev:mp-weixin） │
│ - Alipay：运行至支付宝开发者工具 │
│ - Baidu：运行至百度开发者工具 │
│ - APP：运行至真机或模拟器（HBuilderX→运行到真机） │
└───────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────┐
│ 4. 多端构建 │
│ - H5：npm run build:h5 → 生成 dist/build/h5/ │
│ - mp-weixin：npm run build:mp-weixin → 生成微信小程序代码 │
│ - mp-alipay：npm run build:mp-alipay → 支付宝小程序代码 │
│ - mp-baidu：npm run build:mp-baidu → 百度小程序代码 │
│ - app-plus 本地打包 → 生成 Android APK / iOS IPA │
│ - app-plus 云打包 → 同时生成各平台安装包 │
└───────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────┐
│ 5. 发布上线 │
│ - H5：部署到 HTTPS 服务器（Nginx、Netlify 等） │
│ - 微信小程序：微信开发者工具上传、审核、发布 │
│ - 支付宝小程序：支付宝开发者工具上传、审核、发布 │
│ - 百度小程序：百度开发者工具上传、审核、发布 │
│ - Android：上传至 Google Play、应用商店等 │
│ - iOS：上传至 App Store Connect → 审核 → 发布 │
└───────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────┐
│ 6. 版本维护与迭代 │
│ - 线上 Bug 修复 → 拉取最新分支 → 修改 → 重复上诉流程 │
│ - 持续监控：统计 SDK、Crash 分析、用户反馈 │
│ - 性能优化：打包体积、启动速度、渲染帧率 │
└───────────────────────────────────────────────┘9.1 常见问题汇总
“页面过多导致小程序包体积过大”
- 解决：在
pages.json中配置 分包（subPackages），将不常用或体积大的页面放到子包；首包控制在 2MB 以内。
- 解决：在
“APP 端打包失败：证书签名错误”
- 解决：检查
manifest.json中 iOS/Android 签名配置是否正确，证书与描述文件是否匹配；Android 检查 keystore 路径、密码与别名；iOS 检查 Team ID、mobileprovision 与证书是否一致。
- 解决：检查
“H5 端分享不生效”
- 解决：确保
wx.config中的 URL 与浏览器地址完全一致（包括协议、域名、路径与参数，去掉 hash），并且域名已在微信公众平台-开发配置中添加；确保jsApiList中包含相应分享接口；在wx.ready回调中再调用wx.updateAppMessageShareData等。
- 解决：确保
“小程序端分享图标不显示”
- 解决：小程序分享的
imageUrl必须是远程 HTTPS 链接，不能使用本地static目录路径。
- 解决：小程序分享的
“Android 报 Crash：Missing Splash Screen”
解决：检查
manifest.json中 Android 启动图配置；或在App.vue中手动关闭waiting启动图：onLaunch() { // H5 端可忽略 if (uni.getSystemInfoSync().platform === 'android') { plus.navigator.closeSplashscreen(); } }
“条件编译无效，代码仍然打包”
- 解决：确保使用的是 HBuilderX 打包（
#ifdef只在 HBuilderX 编译时生效）；CLI 模式编译需要在uniapp.config.js中开启相应插件；不要把#ifdef写在同一行注释内。
- 解决：确保使用的是 HBuilderX 打包（
十、总结
本文全面讲解了如何使用 uniapp 实现一次开发、多端发布的完整流程，涵盖以下要点：
- 项目搭建：HBuilderX 或 CLI 快速创建 uniapp 项目；安装 Node.js、Git、各平台开发工具。
- 项目结构与配置：
pages.json管理路由与样式，manifest.json管理 APP 签名与 SDK。 - 跨端差异处理：使用
getPlatform()+ 条件编译指令（#ifdef/#ifndef）区分 APP、H5、小程序代码。 - H5 端开发与发布：本地预览 → 打包 → 部署 HTTPS 服务器；微信公众号需配合 JS-SDK 签名。
- 小程序端开发与发布：本地预览 → 云打包/本地打包 → 微信/支付宝/百度小程序工具上传 → 审核 → 发布。
- 原生 APP 开发与发布：HBuilderX 本地/云打包 → Android APK 签名发布、iOS IPA 签名发布 → App Store/Google Play 审核上架。
- 资源管理与优化：
static/放置静态资源，条件编译剔除端内无关资源；使用分包、懒加载、压缩等技巧优化包体与性能。 - 统一分享示例：借助封装的
shareHandler()实现 APP、小程序、H5/公众号多端一键分享；