运行发布
- 《unibest 官方文档 —— 运行发布》 (opens new window)
- 《unibest 官方文档 —— App 专题》 (opens new window)
- 《uni-app 官方文档 —— 快速上手（云端打包）》 (opens new window)
- 《DCloud 社区 —— Android 平台签名证书说明》 (opens new window)
- 《DCloud 社区 —— Android 签名证书生成指南》 (opens new window)
- 《DCloud 社区 —— iOS 证书和描述文件申请》 (opens new window)
# 1. 环境准备
- Node.js >= 20、pnpm >= 9（见
package.json的engines，项目只允许使用 pnpm 安装依赖），执行pnpm install安装依赖。 - H5、小程序不需要 HBuilderX；App（Android / iOS）需要安装 HBuilderX (opens new window) 并登录 DCloud 账号。HBuilderX 版本尽量与
package.json中@dcloudio/uni-app的版本对应，版本差异过大可能导致打包失败或白屏。
# 2. 环境变量
环境变量统一放在 env 目录，env/.env 是公共配置，各命令再按 mode 叠加对应文件（同名变量以后者为准）：
| 命令 | mode | 读取的文件 |
|---|---|---|
pnpm dev:h5、pnpm dev:mp、pnpm dev:app | development | .env + .env.development |
pnpm build:h5、pnpm build:mp、pnpm build:app | production | .env + .env.production |
pnpm dev:app:test、pnpm build:app:test 等 :test 命令 | test | .env + .env.test |
常用变量如下：
VITE_SERVER_BASEURL：后端请求的基础地址，需带上/admin-api等统一前缀，接口请求及useUpload的上传地址都由它拼接得到。正式环境建议在.env.production中配置，不必改动公共的.env。VITE_APP_PROXY_ENABLE：是否启用代理，仅对 H5 生效。App、小程序不走代理，请求直接发往配置的后端地址。VITE_APP_PUBLIC_BASE：H5 部署的子路径，由manifest.config.ts配置到h5.router.base。VITE_WX_APPID：微信小程序 AppID。VITE_UNI_APPID：App 的 DCloud AppID，见「5.1 准备工作」。- IM 音视频通话支持 H5、App 和微信小程序，开启方式见 《【通话】语音通话、视频通话、共享屏幕》。
友情提示：手机上的 `localhost` 是手机自己，不是你的电脑！
App 真机调试时，VITE_SERVER_BASEURL 要改成电脑的局域网 IP，例如 http://192.168.1.100:48080/admin-api，并确保手机和电脑在同一网络、防火墙放行后端端口。正式发布时请改成可公网访问的 HTTPS 域名。
# 3. H5 运行发布
- 运行：执行
pnpm dev:h5，浏览器访问控制台输出的地址（端口由VITE_APP_PORT配置）。 - 发布：执行
pnpm build:h5，产物在dist/build/h5目录，使用 Nginx 配置静态资源进行发布即可。如果部署在子路径下，需配置VITE_APP_PUBLIC_BASE；如果启用了代理，Nginx 也要转发VITE_APP_PROXY_PREFIX前缀的请求。
# 4. 微信小程序运行发布
- 运行：执行
pnpm dev:mp，使用微信开发者工具导入dist/dev/mp-weixin目录。 - 发布：执行
pnpm build:mp，使用微信开发者工具导入dist/build/mp-weixin目录，点击「上传」后在微信公众平台提交审核。正式环境的后端域名需要配置到小程序后台的 request 合法域名。
# 5. App 运行发布（Android / iOS）
App 的整体流程是：项目编译出 App 资源 → HBuilderX 导入资源 → 云端打包得到 APK / IPA。
# 5.1 准备工作
① 在 DCloud 开发者中心 (opens new window) 创建自己的应用，获取 AppID（格式为 __UNI__xxxxxxx），填写到 env/.env 的 VITE_UNI_APPID。不要直接使用项目模板自带的 AppID，否则可能出现云打包失败或白屏。
② App 的配置以项目根目录的 manifest.config.ts 为准，包括应用名称（VITE_APP_TITLE）、appid、versionName / versionCode、app-plus.distribute 下的 Android 权限 / minSdkVersion / targetSdkVersion / abiFilters、iOS 隐私描述，以及 src/static/app/icons 下的应用图标。
src/manifest.json 是每次 dev / build 时由 manifest.config.ts 自动生成的文件（已被 .gitignore 忽略），不要长期手改它。在 HBuilderX 可视化界面里改过的配置，要同步回 manifest.config.ts，否则下次编译会被覆盖。
友情提示：App 白屏怎么排查？
优先检查：VITE_UNI_APPID 是否为自己的 AppID、HBuilderX 与 uni-app 版本是否对应、后端地址手机能否访问、是否在 App 端加载了只能在浏览器运行的 Web SDK。不建议通过随意降低 minSdkVersion / targetSdkVersion，或全局补 DOMException 等浏览器对象的 polyfill 来“解决”白屏，这样只会掩盖真正的问题。
# 5.2 真机调试
执行 pnpm dev:app，编译产物输出到 dist/dev/app 目录，并持续监听代码变更。
- iOS 模拟器：在 HBuilderX 中导入
dist/dev/app并运行到 iOS 模拟器，修改代码后可热更新。 - Android 模拟器 / 真机：仅导入
dist/dev/app在 Android 上无法热更新，需要把整个项目根目录导入 HBuilderX，再运行到 Android 手机或模拟器。
调试用的工程（dist/dev/app 或项目根目录）和下面打包用的 dist/build/app 不要混用。
# 5.3 构建 App 资源
执行 pnpm build:app（读取 .env.production，测试环境可用 pnpm build:app:test），产物输出到 dist/build/app 目录。
注意，这一步只生成 uni-app 编译后的项目资源（JS、CSS、manifest.json 等），并不是可以安装的 APK / IPA，还需要下一步在 HBuilderX 中打包。
每次修改环境变量（例如后端地址）或 manifest.config.ts 后，都要重新执行 pnpm build:app，再重新打包，否则安装包里还是旧配置。
# 5.4 云端打包
① 在 HBuilderX 中导入 dist/build/app 目录，选中该项目后，点击菜单「发行 → 原生App-云打包」，按平台填写以下信息后提交打包，打包进度和结果可在 HBuilderX 控制台查看。
② Android：
- 包名：建议使用反域名格式，例如
com.example.admin，应用上架后不要再修改。 - 证书：开发阶段可以使用 DCloud 自动生成的「云端证书」；正式发布推荐使用自有证书，使用 JDK 的
keytool生成.keystore文件，别名使用英文或数字，证书文件密码与私钥密码保持一致，打包时填写证书别名、证书私钥密码，并选择证书文件。「公共测试证书」已经下线，不要使用。 - 证书文件、别名、密码务必妥善保管并备份。同一个包名的升级包必须使用同一个证书签名，换证书后的升级包无法覆盖安装。
③ iOS：需要 Apple 开发者账号，并在 Apple 开发者后台准备以下文件。
- Bundle ID：在 Identifiers 中创建 Explicit 类型的 App ID，打包界面的「AppID」栏填写的就是它（注意不是 DCloud AppID）。
- 证书（
.p12）：在 Mac 钥匙串中导出，导出时需要设置密码，打包时要填写该密码。 - 描述文件（
.mobileprovision）：必须基于同一个 Bundle ID 生成，并包含上面的证书。 - 用途区分：开发证书 + 开发描述文件打出的包，可以安装到描述文件登记过的设备上测试，但不能上架；发布证书 + App Store 描述文件打出的包，用于提交 App Store 审核，不能直接安装到手机。
友情提示：证书、密码不要提交到代码仓库！
.keystore、.p12、.mobileprovision 及其密码，建议由专人保管，不要放进 Git 仓库或 env 文件。