部署与发布指南

本指南涵盖爱生活各平台的构建、打包、签名与部署流程。项目基于 uni-app，同一套代码可输出 H5 Web、Android APK/AAB、iOS IPA 三种产物。

1. 构建产物概览

平台	构建命令	产物位置	产物格式
H5	`npm run build:h5`	`dist/build/h5/`	静态文件 (HTML/JS/CSS)
Android	`npm run build:app-android`	`dist/build/app/`	APK / AAB
iOS	`npm run build:app-ios`	`dist/build/app/`	IPA

1.1 构建前检查清单

[ ] npm run type-check 通过（零类型错误）
[ ] 版本号已更新（manifest.json 和 package.json）
[ ] 签名证书已配置（Android/iOS）
[ ] 隐私政策 URL 已更新
[ ] 第三方 SDK Key 已替换为生产环境密钥

2. H5 部署

H5 构建产出一组纯静态文件，可部署到任何静态文件服务器。

2.1 构建

bash

npm run build:h5

构建完成后，产物位于 dist/build/h5/：

dist/build/h5/
├── index.html
├── assets/
│   ├── *.js
│   └── *.css
└── static/

2.2 Nginx 部署

nginx

server {
    listen 80;
    server_name your-domain.com;

    root /var/www/ai-life-os;
    index index.html;

    # 关键配置：ONNX Runtime WASM 需要跨域隔离
    add_header Cross-Origin-Opener-Policy same-origin;
    add_header Cross-Origin-Embedder-Policy credentialless;

    # SPA 路由（hash 模式可选，history 模式必须）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}

重要：Cross-Origin-Opener-Policy 和 Cross-Origin-Embedder-Policy 两个响应头是 H5 端 AI 推理（ONNX Runtime WASM）的必要条件。缺失将导致 SharedArrayBuffer 不可用，端侧 AI 功能白屏。

2.3 Vercel 部署

在项目根目录创建 vercel.json：

json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
        { "key": "Cross-Origin-Embedder-Policy", "value": "credentialless" }
      ]
    }
  ],
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

部署步骤：

bash

npm i -g vercel
npm run build:h5
vercel dist/build/h5 --prod

2.4 GitHub Pages

通过 GitHub Actions 自动部署：

yaml

# .github/workflows/deploy-h5.yml
name: Deploy H5 to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm ci
      - run: npm run build:h5

      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/build/h5
      - uses: actions/deploy-pages@v4

注意：GitHub Pages 不支持自定义 HTTP 响应头，因此 端侧 AI 功能在 GitHub Pages 上不可用。如需完整功能，建议使用 Vercel 或自建服务器。

3. Android 打包

3.1 构建配置

src/manifest.json 中 Android 配置：

配置项	当前值	说明
minSdkVersion	21	Android 5.0+
targetSdkVersion	34	Android 14
ABI	armeabi-v7a, arm64-v8a	32/64 位双架构
包名	com.ailifeos.lutl	应用唯一标识
versionCode	1010	整数版本号（纯递增）
versionName	1.0.10	显示版本号

3.2 生成签名证书

首次打包需生成签名密钥：

bash

keytool -genkey -v \
  -keystore lifeos-release.keystore \
  -alias lifeos \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -storepass <your-store-password> \
  -keypass <your-key-password>

参数说明：

参数	说明
`-keystore`	密钥库文件名
`-alias`	密钥别名
`-keyalg RSA`	密钥算法
`-keysize 2048`	密钥长度
`-validity 10000`	有效期（天），约 27 年

3.3 配置签名

方式一：通过 HBuilderX（推荐）

HBuilderX → 发行 → 原生 App-云打包
在"Android 配置"中选择已生成的 .keystore 文件
填写证书别名和密码
勾选"使用自有证书"

方式二：通过 package.json 配置

json

{
  "uni-app": {
    "scripts": {
      "android": {
        "certpath": "lifeos-release.keystore",
        "keystore": "lifeos-release.keystore",
        "alias": "lifeos",
        "password": "<store-password>",
        "privateKeyPassword": "<key-password>"
      }
    }
  }
}

安全提醒：不要将 keystore 文件和密码提交到 Git 仓库。已在 .gitignore 中配置忽略 *.apk 和 *.pem 文件。建议使用 CI/CD 环境变量管理签名密码。

3.4 构建 APK

bash

npm run build:app-android

产物路径：dist/build/app/android-release.apk（签名后）或 dist/build/app/android-debug.apk（调试版）。

3.5 Google Play 上架

构建 AAB 格式（通过 HBuilderX 云打包选择 AAB）
登录 Google Play Console → 创建应用
上传 AAB → 填写应用信息（描述、截图、隐私政策）
提交审核

AAB vs APK：Google Play 要求新应用使用 AAB 格式。AAB 文件更小，Google 会根据设备自动生成优化后的 APK。

3.6 国内应用市场

主流国内市场需额外处理：

市场	特殊要求
华为应用市场	需 HMS SDK 集成
小米应用商店	标准 APK 即可
OPPO/VIVO	标准 APK 即可
腾讯应用宝	可能需额外 SDK

注意：若应用包含 AI 对话功能，需确认各市场的 AI 生成内容合规要求。

4. iOS 打包

4.1 构建配置

src/manifest.json 中 iOS 配置：

配置项	当前值	说明
appid	空（待配置）	Apple Developer 分配的 Bundle ID
dSYMs	false	调试符号文件
部署目标	iOS 12+	uni-app 3.0 默认支持

4.2 证书管理

iOS 打包需要两种证书：

证书类型	用途	获取方式
开发证书 (Development)	真机调试	Apple Developer Portal
发布证书 (Distribution)	App Store / TestFlight	Apple Developer Portal

同时需要对应的描述文件（Provisioning Profile），包含：

App ID（Bundle ID）
设备 UDID 列表（开发证书）
证书关联

4.3 构建 IPA

方式一：通过 HBuilderX 云打包（推荐，无需 Mac）

HBuilderX → 发行 → 原生 App-云打包
选择 iOS 平台
上传开发/发布证书（.p12）和描述文件（.mobileprovision）
填写 Bundle ID
开始打包

方式二：本地 Xcode 打包（需 macOS）

bash

npm run build:app-ios
# 然后用 Xcode 打开 dist/build/app/ 下的 .xcodeproj

4.4 TestFlight 分发

在 App Store Connect 中创建 App 记录
通过 Xcode 或 Transporter 上传 IPA
填写测试信息（Beta App 描述、测试员邮箱）
邀请内部测试员（最多 100 人）
测试员通过 TestFlight App 安装测试

TestFlight 是正式上架前的推荐测试方式，无需设备 UDID，支持最多 10,000 名外部测试员。

4.5 App Store 上架

在 App Store Connect 中完善 App 信息（描述、截图、隐私标签）
提交 App 审核
审核通过后发布

隐私标签要求：App Store 要求填写 App 隐私详情。爱生活应声明：

标识符：不收集
使用数据：不收集
诊断数据：不收集
位置：仅在使用时（轨迹记录功能）
音频：仅在使用时（语音输入功能）

5. 版本管理

5.1 版本号体系

字段	文件	说明
version	`package.json`	npm 包版本号
versionName	`manifest.json`	用户可见版本号（如 1.0.0）
versionCode	`manifest.json`	整数内部版本号（每次发布 +1）

5.2 发版流程

① 确认功能冻结，type-check 通过
② 更新版本号：
   manifest.json: versionCode += 1, versionName = "x.y.z"
   package.json: version = "x.y.z"
③ npm run docs:build    # 更新文档站点
④ 构建各平台产物（H5 / Android APK / wgt 资源包）
⑤ 上传 APK/wgt 到静态托管，更新 version.json（版本号、changelog、下载地址、sha256、size、rollout）
⑥ git tag vx.y.z && git push --tags
⑦ 部署 H5 / 上传应用市场

5.3 语义化版本

遵循 SemVer 规范：

变更类型	版本号	示例
不兼容的 API 修改	主版本号 +1	1.0.0 → 2.0.0
向下兼容的功能新增	次版本号 +1	1.0.0 → 1.1.0
向下兼容的问题修复	修订号 +1	1.0.0 → 1.0.1

6. 环境变量

项目通过 env.d.ts 声明了如下环境变量类型：

变量	用途	默认值
`VITE_APP_TITLE`	应用标题	爱生活
`VITE_SYNC_ENABLED`	启用同步功能	false
`VITE_ENCRYPTION_KEY`	默认加密密钥	—

创建 .env.production 配置生产环境变量：

bash

VITE_APP_TITLE=爱生活
VITE_SYNC_ENABLED=true

注意：.env 文件不应提交到 Git。实际环境变量值通过构建环境注入。

7. 文档站点部署

文档站点基于 VitePress，同样产出纯静态文件：

bash

npm run docs:build

产物位于 docs/.vitepress/dist/，可直接部署到任意静态服务器。

Vercel 一键部署文档

bash

npm run docs:build
vercel docs/.vitepress/dist --prod

GitHub Pages 部署文档

与 H5 部署类似，将 docs/.vitepress/dist/ 作为 GitHub Pages 源目录。

8. 应用更新机制

8.1 当前实现（Phase 0，详见 docs/update-and-analytics.md）

统一由 静态版本清单 version.json 驱动，核心代码：

src/services/update.service.ts — 版本检测 / 灰度 / 下载 / 校验 / 安装
src/pages/update/index.vue — 检查更新页（含下载进度、强制更新、wgt 重启提示）
src/constants/app.ts + vite.config.ts — 构建期版本注入
src/static/version.json — H5 开发兜底清单（uni-app 会原样拷贝到产物）

平台	更新方式
Android	整包 APK 下载安装（`plus.downloader` 带进度 → 大小 + SHA-256 校验 → `plus.runtime.install`），或 wgt 热更新
iOS	wgt 热更新（正式版本走 TestFlight / App Store）
H5	部署新版本后刷新 / 跳转新地址
小程序	走微信发布体系

检查入口：解锁后自动检查（App.vue 监听 appLocked → 全局更新弹窗 UpdatePrompt），任何页面直接弹出，不跳转；设置页「检查更新」支持手动检查。完整流程与发布操作见 docs/release-guide.md。

配置：App 端无需配置——代码内置默认指向 https://gitee.com/lutlelk/ai-life-os-release/raw/master/version.json（HBuilderX 云打包不带 .env 也能用）；仅自建服务器/其它托管时在 CLI 构建的 .env.production 设置 VITE_UPDATE_MANIFEST_URL 覆盖。H5 端同源 /static/version.json。

8.2 发版清单

Android 8+ 整包安装需在 HBuilderX 云打包配置 REQUEST_INSTALL_PACKAGES 权限
iOS wgt 热更新属灰色地带（Apple 禁止下载代码改变功能），仅限小修小补
version.json 的 HTTP 缓存 TTL 建议设短（60s）或 no-cache

9. CI/CD 建议

9.1 GitHub Actions — H5 自动部署

已在 H5 部署章节提供示例配置。核心流程：checkout → npm ci → build → deploy。

9.2 GitHub Actions — 类型检查门禁

yaml

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npm run type-check

9.3 构建缓存优化

yaml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

10. 安全检查清单

发布前请确认以下安全事项：

[ ] 生产构建未包含 debug 日志
[ ] 签名证书私钥安全存储（未提交至仓库）
[ ] 第三方 SDK Key 未被硬编码（通过环境变量注入）
[ ] 高德地图 Key 等已替换为生产环境密钥
[ ] 隐私政策 URL 可访问且内容完整
[ ] manifest.json 中未声明不需要的权限
[ ] App 传输安全（ATS）配置正确（iOS）
[ ] targetSdkVersion 满足 Google Play 最新要求

部署与发布指南 ​

1. 构建产物概览 ​

1.1 构建前检查清单 ​

2. H5 部署 ​

2.1 构建 ​

2.2 Nginx 部署 ​

2.3 Vercel 部署 ​

2.4 GitHub Pages ​

3. Android 打包 ​

3.1 构建配置 ​

3.2 生成签名证书 ​

3.3 配置签名 ​

3.4 构建 APK ​

3.5 Google Play 上架 ​

3.6 国内应用市场 ​

4. iOS 打包 ​

4.1 构建配置 ​

4.2 证书管理 ​

4.3 构建 IPA ​

4.4 TestFlight 分发 ​

4.5 App Store 上架 ​

5. 版本管理 ​

5.1 版本号体系 ​

5.2 发版流程 ​

5.3 语义化版本 ​

6. 环境变量 ​

7. 文档站点部署 ​

Vercel 一键部署文档 ​

GitHub Pages 部署文档 ​

8. 应用更新机制 ​

8.1 当前实现（Phase 0，详见 docs/update-and-analytics.md） ​

8.2 发版清单 ​

9. CI/CD 建议 ​

9.1 GitHub Actions — H5 自动部署 ​

9.2 GitHub Actions — 类型检查门禁 ​

9.3 构建缓存优化 ​

10. 安全检查清单 ​

部署与发布指南

1. 构建产物概览

1.1 构建前检查清单

2. H5 部署

2.1 构建

2.2 Nginx 部署

2.3 Vercel 部署

2.4 GitHub Pages

3. Android 打包

3.1 构建配置

3.2 生成签名证书

3.3 配置签名

3.4 构建 APK

3.5 Google Play 上架

3.6 国内应用市场

4. iOS 打包

4.1 构建配置

4.2 证书管理

4.3 构建 IPA

4.4 TestFlight 分发

4.5 App Store 上架

5. 版本管理

5.1 版本号体系

5.2 发版流程

5.3 语义化版本

6. 环境变量

7. 文档站点部署

Vercel 一键部署文档

GitHub Pages 部署文档

8. 应用更新机制

8.1 当前实现（Phase 0，详见 docs/update-and-analytics.md）

8.2 发版清单

9. CI/CD 建议

9.1 GitHub Actions — H5 自动部署

9.2 GitHub Actions — 类型检查门禁

9.3 构建缓存优化

10. 安全检查清单