项目部署

本页说明 youlai-app 的 H5、微信小程序、Android、iOS 构建与发布。分包设计见分包开发。

构建前检查

检查项	说明
依赖已安装	在 `youlai-app` 目录执行 `pnpm install`
环境变量已配置	H5 主要看 `VITE_APP_BASE_API`，小程序和 App 主要看 `VITE_APP_API_URL`
接口地址可访问	真机、小程序和 App 不能依赖浏览器代理，需要可访问的后端完整地址
`src/manifest.json` 已确认	小程序 AppID、App 名称、版本号、权限配置按实际项目调整
生产资源已处理	图片压缩、静态资源清理，微信小程序注意主包体积

常用命令

平台	开发命令	构建命令	产物目录 / 说明
H5	`pnpm run dev:h5`	`pnpm run build:h5`	`dist/build/h5/`
微信小程序	`pnpm run dev:mp-weixin`	`pnpm run build:mp-weixin`	`dist/build/mp-weixin/`
App	`pnpm run dev:app`	`pnpm run build:app`	生成 App 资源，通常配合 HBuilderX 打包
Android	`pnpm run dev:app-android`	`pnpm run build:app-android`	Android 平台构建资源
iOS	`pnpm run dev:app-ios`	`pnpm run build:app-ios`	iOS 平台构建资源

H5 打包与部署

构建

bash

pnpm run build:h5

构建产物：

text

dist/build/h5/

部署

将 dist/build/h5/ 上传到 Nginx、对象存储或静态托管平台。

Nginx 示例：

nginx

server {
    listen 80;
    server_name app.example.com;
    root /var/www/youlai-app;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /prod-api/ {
        proxy_pass http://127.0.0.1:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

H5 注意事项

问题	处理方式
刷新 404	配置 `try_files $uri $uri/ /index.html`
接口跨域	生产环境用 Nginx 反向代理，或后端配置 CORS
静态资源路径异常	检查部署路径和 Vite/uni-app 的基础路径配置

微信小程序打包与发布

构建

bash

pnpm run build:mp-weixin

构建产物：

text

dist/build/mp-weixin/

导入微信开发者工具

打开微信开发者工具。
导入 dist/build/mp-weixin。
AppID 使用 src/manifest.json 中 mp-weixin.appid 对应的小程序 AppID。
本地调试时可在「详情 → 本地设置」中勾选“不校验合法域名、web-view、TLS 版本以及 HTTPS 证书”。
真机预览确认登录、接口请求、文件上传和页面跳转。
点击「上传」，再到微信公众平台提交审核。

微信小程序注意事项

问题	处理方式
接口请求失败	小程序需要 HTTPS 合法域名，生产环境不要依赖本地代理
上传体积超限	使用分包开发，图片走 CDN，删除无用资源
分包页面打不开	检查 `dist/build/mp-weixin/app.json` 中是否生成 `subPackages`
组件缺失	本地设置中不要勾选“过滤无依赖文件”，并重新构建

App 打包说明

uni-app 的 App 发布通常分两步：先生成 App 平台资源，再用 HBuilderX 云打包或本地原生工程完成安装包。

通用 App 构建

bash

pnpm run build:app

Android 构建

bash

pnpm run build:app-android

后续可用 HBuilderX 打开项目并执行：

发行 → 原生 App-云打包。
选择 Android。
配置包名、证书、版本号、权限。
提交云打包，下载 APK / AAB。
真机安装测试登录、接口、上传、相机、文件等能力。

iOS 构建

bash

pnpm run build:app-ios

后续可用 HBuilderX 打开项目并执行：

发行 → 原生 App-云打包。
选择 iOS。
配置 Bundle ID、证书、描述文件、版本号。
提交云打包，生成 ipa。
使用 TestFlight 或真机安装方式测试。

App 配置入口

App 相关配置主要在 src/manifest.json：

配置	说明
`name`	应用名称
`appid`	DCloud AppID，本地为空时按实际项目补充
`versionName`	展示版本号
`versionCode`	构建版本号
`app-plus.distribute.android`	Android 权限、证书、渠道等配置
`app-plus.distribute.ios`	iOS 证书、Bundle ID 等配置

App 注意事项

问题	处理方式
App 请求失败	使用 HTTPS，检查真机能否访问 `VITE_APP_API_URL`
Android HTTP 请求失败	优先配置 HTTPS；如必须 HTTP，需要额外检查 Android 网络安全策略
权限弹窗异常	核对 `manifest.json` 中 Android / iOS 权限配置
iOS 打包失败	检查 Bundle ID、证书、描述文件是否匹配
版本未更新	同步更新 `versionName` 和 `versionCode`

环境变量

文件	说明
`.env.development`	开发环境
`.env.production`	生产环境

关键变量：

变量	说明	常见平台
`VITE_APP_BASE_API`	API 代理前缀，例如 `/dev-api`、`/prod-api`	H5
`VITE_APP_API_URL`	后端完整地址，例如 `https://api.example.com`	微信小程序、App
`VITE_APP_PORT`	H5 开发端口	H5 开发

发布前检查清单

[ ] H5 已验证刷新、登录、接口请求和静态资源路径。
[ ] 微信小程序已真机预览，合法域名、分包体积和上传流程正常。
[ ] Android 已真机安装，网络请求、权限、文件上传正常。
[ ] iOS 已通过 TestFlight 或真机方式验证核心流程。
[ ] 生产接口地址、版本号、AppID、证书和权限配置已确认。
[ ] 如启用分包，已检查生成产物中的 subPackages 和页面路径。

项目部署 ​

构建前检查 ​

常用命令 ​

H5 打包与部署 ​

构建 ​

部署 ​

H5 注意事项 ​

微信小程序打包与发布 ​

构建 ​

导入微信开发者工具 ​

微信小程序注意事项 ​

App 打包说明 ​

通用 App 构建 ​

Android 构建 ​

iOS 构建 ​

App 配置入口 ​

App 注意事项 ​

环境变量 ​

发布前检查清单 ​

相关文档 ​

项目部署

构建前检查

常用命令

H5 打包与部署

构建

部署

H5 注意事项

微信小程序打包与发布

构建

导入微信开发者工具

微信小程序注意事项

App 打包说明

通用 App 构建

Android 构建

iOS 构建

App 配置入口

App 注意事项

环境变量

发布前检查清单

相关文档