117 lines
8.6 KiB
Markdown
117 lines
8.6 KiB
Markdown
# uni-app 原生发行配置
|
||
|
||
H5 构建不依赖厂商证书。`pnpm check:native` 检查 AppID 基础格式、模块、隐私声明及 HTTPS/WSS 地址；不会验证开发者账号、AppID 归属或签名证书，这些仍由 HBuilderX/DCloud 打包流程校验。
|
||
|
||
1. 在 DCloud 开发者中心创建应用，将实际分配的 AppID 写入 `src/manifest.json` 的 `appid`，不要自行拼造。预检兼容 7 位和 8 位十六进制后缀，保留当前项目已有的 AppID。
|
||
2. 在 HBuilderX 的可视化 manifest 中配置应用包名、Android 签名证书和 iOS Bundle ID/证书。证书及密码不要提交到 Git。
|
||
3. 按实际厂商填写微信/QQ登录、微信/支付宝支付和 UniPush 参数。客户端只展示后端 `/api/v1/auth/oauth/providers` 与 `/api/v1/payment/channels` 返回且已启用的渠道。
|
||
4. 在 `mobile/.env.production` 配置 `VITE_API_ORIGIN` 和 `VITE_WS_ORIGIN`，预检和生产构建都会读取。终端/CI 显式注入的同名变量优先。域名必须具有有效 TLS 证书，反向代理须放行 `/ws` 升级连接。当前配置为 `https://im.bchongw.com` 和 `wss://im.bchongw.com`。
|
||
5. Android 仅保留网络、定位、相机、录音和振动权限；iOS 的对应隐私用途说明已写入 manifest。首次使用能力时由页面按需申请，不在启动时集中索权。
|
||
6. 运行下面的检查命令，再执行 `pnpm build:app-plus` 或使用 HBuilderX 云打包。
|
||
|
||
第三方 AppID、密钥、商户证书、短信签名和主体备案信息必须由真实主体申请，仓库不会提供可冒用的演示密钥。
|
||
|
||
## 在 HBuilderX 中导入及重新编译
|
||
|
||
本仓库的移动端是 Vue 3 CLI 工程。建议通过「文件 → 导入 → 从本地目录导入」选择 **`D:\web\age\im\mobile` 整个目录**，不要只选择 `mobile/src`。
|
||
|
||
- 整个工程导入会使用项目依赖，并保留根目录的 `vite.config.ts` 和 `.env` 配置。
|
||
- 只导入 `src` 也是 HBuilderX 支持的另一种方式，但会改用 HBuilderX 内置编译器，工程根目录和环境配置位置也会变化，不适合直接沿用本项目的 CLI 配置。
|
||
- 如果日志标签显示 `src - Xiaomi ...`，请检查当前选中的是否是单独导入的 `src` 工程。无需删除源码，重新导入并选择完整的 `mobile` 工程即可。
|
||
|
||
停止旧的运行任务，保存文件，再从「运行 → 运行到手机或模拟器」重新运行。生成安装包则使用「发行 → 原生 App 云打包」，根据实际发布平台填写包名和签名材料；签名/云打包成功才代表生成 APK/IPA。
|
||
|
||
## 真机调试与生产环境
|
||
|
||
### HBuilderX 提示找不到本地 Node.js
|
||
|
||
本机 Node.js 路径是 `C:\nvm4w\nodejs\node.exe`，版本 `v22.22.0`。2026-08-31 已确认 HBuilderX 的 Node 检测先调用 `where node`；原 PATH 遗漏 `C:\Windows\System32`，导致 `where.exe` 找不到，从而误报 Node 未安装。
|
||
|
||
已仅向当前用户 PATH 补入 `C:\Windows\System32`，原有条目保留，系统级 PATH 未改动。通过 HBuilderX 自带 Node 重现其检测步骤，已能找到本机 Node.js。修改前的 PATH 备份在仓库 `.tools/hbuilderx-path-backup-20260831.json`（不提交到版本库）。
|
||
|
||
保存文件并完全退出 HBuilderX，再重新打开完整 `mobile` 工程，使新进程读取更新后的环境变量。可在新终端验证：
|
||
|
||
```powershell
|
||
where.exe node
|
||
node --version
|
||
npm --version
|
||
```
|
||
|
||
不要为解决这一提示删除项目依赖、修改 HBuilderX 插件或重复安装 Node。
|
||
|
||
### 接口域名
|
||
|
||
`mobile/.env.production` 用于发行构建；HBuilderX「运行到手机/模拟器」使用 development 模式，不读取 `.env.production`。已在 `mobile/.env.development` 配置部署服务，调试和发行均可访问 `https://im.bchongw.com`，消息地址为 `wss://im.bchongw.com`。测试操作会使用该部署环境的真实数据。
|
||
|
||
如需独立测试服务器，可在 `mobile/.env.development.local` 覆盖地址。H5 本地开发也会读取 development 配置，请明确选择所需后端：
|
||
|
||
```dotenv
|
||
VITE_API_ORIGIN=https://im.bchongw.com
|
||
VITE_WS_ORIGIN=wss://im.bchongw.com
|
||
```
|
||
|
||
连接开发电脑上的后端时需要手机可访问的 HTTPS 地址（也可使用可信的 HTTPS 开发隧道）。手机上的 `127.0.0.1` 指向手机自身，不是开发电脑。不要把后端密钥、数据库密码或商户私钥放进任何 `VITE_` 变量，它们会被编入客户端。
|
||
|
||
`dev:app-plus` 现在按 `--mode development` 预检，`build:app-plus` 按 `--mode production` 预检，并输出实际 API/WS 地址。预检拒绝回环地址。运行时会区别提示接口配置错误、DNS 失败、证书失败和超时，不会关闭 TLS 证书校验。
|
||
|
||
`VITE_H5_BASE=/app/` 仅用于 H5 网站，App 构建不会再沿用该网站子路径。环境文件读取位置固定为工程目录，不依赖 HBuilderX 启动时的工作目录。
|
||
|
||
## 检查与 App 资源编译
|
||
|
||
在 `mobile` 目录执行：
|
||
|
||
```powershell
|
||
pnpm test:native-components
|
||
pnpm test:icons
|
||
pnpm test:native-config
|
||
pnpm type-check
|
||
pnpm check:native
|
||
pnpm build:app-plus
|
||
pnpm build:h5
|
||
```
|
||
|
||
当前 CLI 编译器将 App 资源输出到 `dist/build/app`，H5 输出到 `dist/build/h5`。App 资源不是已签名 APK/IPA；本次仅验证了资源编译，没有提交云打包、签名或安装到用户手机。
|
||
|
||
## 已修复的 switch 编译错误
|
||
|
||
原隐私设置和消息通知页面使用了 `<switch v-model="...">`，App Vue 编译时报 `v-model can only be used on <input>, <textarea> and <select> elements`。
|
||
|
||
两处均改为 `:checked` 配合 `@change`，在事件处理函数中用 `event.detail.value` 更新表单。已有的保存接口和样式保持不变，加载/保存期间禁止切换。回归测试覆盖全部 Vue 模板中的原生控件绑定，以及两个页面的开/关状态更新。
|
||
|
||
参考：[switch 官方文档](https://uniapp.dcloud.net.cn/component/switch.html)、[CLI 与 HBuilderX 工程的区别](https://uniapp.dcloud.net.cn/quickstart?id=quickapp)、[Vite 配置说明](https://uniapp.dcloud.net.cn/collocation/vite-config.html)。
|
||
|
||
## 已修复的 App 内功能图标空白
|
||
|
||
2026-08-31：截图中头像和文字正常，但底部导航、发布加号、定位等图标一起缺失。原因在共享 `src/components/AppIcon.vue`：之前直接把 `<svg>/<path>` 放在 uni-app 模板中，App-vue 的组件渲染链路不支持这种写法。这不是 COS 图片链接问题，也不是应用桌面启动图标的问题。
|
||
|
||
现已改为标准 `<view>` 组件，使用内置的 SVG 图片数据作为 CSS 遮罩，保留原有 39 个图标的几何形状、空心/实心状态、主题颜色和尺寸；同时提供 `-webkit-mask-*` 样式。所有图形都在安装包的 JS 中，不需要外网图标地址、字体下载或额外的 static 文件拷贝。
|
||
|
||
验证方式：
|
||
|
||
```powershell
|
||
# 在 mobile 目录执行。
|
||
pnpm test:icons
|
||
pnpm test:native-components
|
||
pnpm type-check
|
||
pnpm build:app-plus
|
||
pnpm build:h5
|
||
|
||
# 单独检查已经生成的 App 资源：
|
||
pnpm verify:app-icons
|
||
```
|
||
|
||
`build:app-plus` 已自动执行图标产物检查：必须包含内置 SVG 图片数据、双套遮罩属性和首页/附近/消息/动态/个人主页/聊天/会员 7 个页面的组件样式，不得残留原始 SVG 模板组件。
|
||
|
||
如需本地可视检查，可运行 `node scripts/preview-icons.mjs`，打开终端显示的本地地址。该预览直接编译实际 `AppIcon` 和 `BottomNav` 组件，使用隔离的未读数示例，不登录账号、不连接生产接口。可检查所有图标、深浅背景、实心切换、颜色切换和底部导航。此次浏览器手机尺寸预览的 51 个图标实例显示正常，颜色/实心切换和构建检查通过；未将浏览器结果当作 Android/iOS 真机验收。
|
||
|
||
### 如何让手机上的 App 使用修复
|
||
|
||
1. 在 HBuilderX 选择完整的 `D:\web\age\im\mobile` 工程，保存所有文件并停止旧的运行任务。
|
||
2. 真机调试：重新执行“运行到手机或模拟器”，让 HBuilderX 重新编译并同步资源。
|
||
3. 安装包：重新执行“发行 → 原生 App 云打包”，安装新生成的包。更新网站、后端或只刷新手机上的旧 APK 不会替换包内组件代码。
|
||
4. 如仍看到旧样式，先检查选中的工程路径以及打包时间；不要删除用户数据或卸载 App 来排查缓存。
|
||
|
||
本次生成的是 `dist/build/app` 资源，不是已签名 APK/IPA；没有提交云打包或安装到用户手机。需要在新包装到手机后确认底部五个图标及页面中的功能图标。
|
||
|
||
参考：[DCloud 关于 App-vue 中 SVG 图片与模板标签的说明](https://ask.dcloud.net.cn/question/67267)、[CSS mask-image](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/mask-image)。
|