logoDocumentation center
VortMall 技术指南

iOS APP 发布与证书申请指南

VortMall iOS APP 发布与证书申请指南

本文档介绍如何将 VortMall 开源商城 UniApp 端（vortmall-uniapp/）打包并发布到 iOS 平台，涵盖证书申请、云打包、真机测试与 App Store 上架全流程。

目录

  1. 前置准备
  2. 配置生产环境变量
  3. 配置 manifest.json
  4. 注册 Apple 开发者账号
  5. 证书类型说明
  6. 生成 CSR 证书签名请求
  7. 创建 App ID
  8. 申请开发与发布证书
  9. 添加调试设备
  10. 创建描述文件（Provisioning Profile）
  11. 导出 P12 证书
  12. HBuilderX 云打包与 Xcode 配置
  13. 测试应用
  14. 发布到 App Store
  15. 常见问题

1. 前置准备

发布 iOS 应用需要以下环境与账号：

项目说明
Apple 开发者账号已加入 Apple Developer Program（个人/公司 99 美元/年，企业 299 美元/年）
Mac 电脑必须使用 macOS 系统（生成 CSR、导出 P12、Xcode 打包均依赖 Mac）
Xcode安装最新版 Xcode（真机调试、Archive 上传 App Store）
HBuilderX打开 vortmall-uniapp/ 工程并进行云打包
UniApp 项目确保项目在 HBuilderX 中可正常运行
iOS 设备（可选）用于真机调试与测试

说明：若已通过第三方工具或旧 Mac 申请过 P12 证书，可在 Windows 等非 Mac 环境使用已有证书进行云打包；但首次申请证书仍建议在 Mac 上完成。

2. 配置生产环境变量

在 vortmall-uniapp/ 根目录创建或修改 .env.production。

按实际环境修改 VITE_API_URL、VITE_API_PREFIX（以及项目中使用到的其它变量），示例：

# .env.production
VITE_API_URL=https://xxx.xxx.xxx
VITE_API_PREFIX=/api
VITE_STATIC_RESOURCE=/static
VITE_NODE_ENV=production

# （可选）MQTT 地址
# VITE_MQTT_URL=wss://xxx.xxx.xxx/mqtt

VortMall 项目完整变量说明

VortMall 工程实际还包含以下环境变量（可复制 vortmall-uniapp/.env.example 作为模板）：

# WebSocket 地址（IM 聊天、消息推送等）
VITE_SOCKET_URL=wss://xxx.xxx.xxx

# 功能开关（1=启用，0=禁用，按部署版本裁剪功能）
VITE_IS_MERCHANT=1   # 多商户
VITE_IS_PRO=1        # 专业版
VITE_IS_B2B=1        # B2B
VITE_IS_OVERSEAS=1   # 海外版
VITE_PROXY=0
变量说明
VITE_API_URL后端 API 根地址，必填，须为可公网访问的 HTTPS 地址
VITE_API_PREFIXAPI 路径前缀，默认 /api/
VITE_STATIC_RESOURCE静态资源路径，官方示例为 /static；部分部署环境使用 api/static/mini，以实际后端配置为准
VITE_SOCKET_URLWebSocket 地址，用于实时通讯
VITE_MQTT_URLMQTT over WebSocket 地址，用于 IM 聊天、消息计数等推送（详见 vortmall-uniapp/docs/MQTT 前端对接文档.md）
VITE_IS_*业务版本功能开关，影响打包时模块裁剪

修改环境变量后需重新编译/打包，否则不会生效。不要将包含真实密钥的 .env.production 提交到公开仓库。

3. 配置 manifest.json

编辑 vortmall-uniapp/src/manifest.json，确认/修改以下信息：

  • name：应用名称
  • appid：DCloud 应用标识（用于云打包）
  • versionName：版本名称（如 1.0.0）
  • versionCode：版本号（整数递增，如 100、101）
  • 包名（Bundle ID）：在 HBuilderX 可视化界面「App 常用其它设置」中配置，须与 Apple Developer 中创建的 App ID 完全一致
  • app-plus.distribute.ios.privacyDescription：iOS 隐私权限文案
  • app-plus.distribute.icons.ios：iOS 图标（建议填写项目内相对路径，不要使用本机绝对路径）
  • 权限设置：相机、相册、定位等按需配置

修改后保存，在 HBuilderX 中重新编译确认项目可正常运行。更多开发配置参见 VortMall · UniApp 开发配置。

3.1 VortMall 当前预置配置参考

{
    "name": "vortmall",
    "appid": "__UNI__F1B77AA",
    "versionName": "1.0.0",
    "versionCode": "100"
}

iOS 隐私权限文案（app-plus.distribute.ios.privacyDescription）：

"privacyDescription": {
    "NSCameraUsageDescription": "此App会在拍摄自定义头像时访问您的相机权限",
    "NSPhotoLibraryUsageDescription": "此App会在选择自定义头像时访问您的相册权限",
    "NSLocationWhenInUseUsageDescription": "此App需要获取您的位置信息，用于定位附近门店和配送服务"
}

已启用 App 模块（app-plus.modules）：Camera、Geolocation、Payment、VideoPlayer。

支付配置（app-plus.distribute.sdkConfigs.payment）：已配置支付宝（iOS/Android 双端）。

3.2 iOS 图标配置注意

打包前请将图标路径改为项目内相对路径，例如：

"icons": {
    "ios": {
        "appstore": "static/icon/appstore.png",
        "iphone": {
            "app@2x": "static/icon/icon@2x.png",
            "app@3x": "static/icon/icon@3x.png"
        }
    }
}

不要使用 /Users/xxx/... 或 C:/Users/... 等本机绝对路径，否则云打包时图标无法正确读取。静态资源存放规范参见 VortMall · uniapp端静态资源存放说明。

4. 注册 Apple 开发者账号

若尚未开通开发者账号，按以下步骤注册：

  1. 使用有效的 Apple ID 登录 Apple Developer。
  2. 点击 Join the Apple Developer Program。
  3. 选择账号类型：
    • 个人账号：99 美元/年，适用于独立开发者，可上架 App Store。
    • 公司/组织账号：99 美元/年，需提供 D-U-N-S 编号，苹果可能电话核实。
    • 企业账号：299 美元/年，用于内部分发，不可上架 App Store。
  4. 填写资料并支付年费，审核通过后账号激活。

5. 证书类型说明

证书类型用途有效期数量限制
Apple Development（开发证书）真机调试、开发测试1 年每个账号最多 2 个
Apple Distribution（发布证书）App Store 上架、Ad Hoc 内测分发1 年每个团队最多 1 个
APNs Development开发环境推送通知1 年每个 App ID 1 个
APNs Distribution生产环境推送通知1 年每个 App ID 1 个

描述文件（.mobileprovision）类型：

类型用途
iOS App Development开发调试，需绑定测试设备 UDID
Ad Hoc内测分发，仅描述文件内包含 UDID 的设备可安装
App Store上架 App Store 的正式包

6. 生成 CSR 证书签名请求

CSR（Certificate Signing Request）是所有证书申请的第一步，用于生成公钥和私钥对。

6.1 打开钥匙串访问

在 Mac 上打开 钥匙串访问（Launchpad → 其他 → 钥匙串访问）。

6.2 创建 CSR 文件

  1. 顶部菜单选择：钥匙串访问 → 证书助理 → 从证书颁发机构请求证书...

image.png

  1. 在「证书信息」窗口中填写：
    • 用户电子邮件地址：开发者账号邮箱
    • 常用名称：姓名或公司名称
    • 请求是：选择 存储到磁盘
    • 不要勾选「让我指定密钥对信息」

image.png

image.png

  1. 点击 继续，选择保存位置（建议桌面）。
  2. 文件名保持默认 CertificateSigningRequest.certSigningRequest，点击 存储 → 完成。

生成成功后，在钥匙串访问的 密钥 分类中会出现新的公钥和私钥对。请妥善保管私钥，后续导出 P12 时需要用到。

7. 创建 App ID

每个 iOS 应用都需要唯一的 App ID（Bundle ID），且须与 UniApp 项目 manifest.json 中的包名一致。

7.1 进入标识符管理

  1. 登录 Apple Developer。
  2. 左侧选择 Certificates, Identifiers & Profiles。
  3. 选择 Identifiers，点击右上角 +。

7.2 填写 App ID 信息

  1. 标识类型选择 App IDs，点击 Continue。
  2. 平台选择 iOS, tvOS, watchOS。
  3. Bundle ID 选择 Explicit（明确的）。
  4. Description：填写应用描述。
  5. Bundle ID：填写唯一标识，建议反域名格式，例如：
    • com.companyname.vortmall
    • io.dcloud.hellouniapp
  6. 根据需求勾选服务（如 Push Notifications 推送、iCloud 等）。
  7. 点击 Continue → Register 完成创建。

若 App ID 已存在，可跳过本节，直接进入证书申请。

8. 申请开发与发布证书

8.1 登录开发者平台

  1. 打开浏览器访问 Apple Developer 官方网站。
  2. 使用你的开发者账号登录（需开启双重认证）。
  3. 点击左侧导航栏的 Certificates, IDs & Profiles 进入证书管理中心。

11企业微信截图_7276076e-b3d5-4b2d-bac7-d6abaa0018d1.jpg

image.png

8.2 申请开发证书（Apple Development）

  1. 用于将应用安装到真机进行调试测试。
  2. 在左侧选择 Certificates，然后点击右上角的 + 创建新证书。
  3. 在 "Create a New Certificate" 页面，选择 Apple Development（或 iOS App Development），点击 Continue。
  4. 在 "Upload a Certificate Signing Request" 页面，点击 Choose File，选择第 6 节生成的 CertificateSigningRequest.certSigningRequest 文件。
  5. 点击 Continue，苹果服务器将自动生成证书。
  6. 证书生成成功后，点击 Download 下载证书文件（development.cer）。
  7. 双击 .cer 文件将其导入钥匙串。

image.png

33企业微信截图_4259d736-5a6e-4a1a-a06a-db0103b06ee2.jpg

8.3 申请发布证书（Apple Distribution）

  1. 用于将应用上架到 App Store 或进行 Ad Hoc 企业内测分发，申请流程与开发证书完全相同：
  2. 回到 Certificates 页面，再次点击右上角的 +。
  3. 选择 Apple Distribution（或 iOS Distribution），点击 Continue。
  4. 上传同一个 CSR 文件（无需重新生成），点击 Continue。
  5. 下载生成的发布证书（distribution.cer）。
  6. 双击 .cer 文件将其导入钥匙串。

重要提示：每个团队只能有一个有效的 Apple Distribution 证书。如果提示「证书数量超过限制」，请先删除过期或不再使用的旧证书（删除旧证书不会影响已上架应用的正常运行）。

8.4 安装证书到钥匙串

  1. 在钥匙串访问中选择 登录 钥匙串 → 证书 分类。
  2. 确认证书已安装且显示为「此证书已被此账户信任」。

若证书显示「不受信任」，请检查系统日期时间是否正确，或重新下载 Apple 根证书。

9. 添加调试设备

开发描述文件和 Ad Hoc 描述文件需要绑定测试设备的 UDID。

  1. 在证书管理页面选择 Devices，点击 +。
  2. 填写 设备名称 和 UDID。
  3. 点击 Continue 完成添加。

获取设备 UDID 的方法：

  • Xcode：连接设备 → Window → Devices and Simulators → 选中设备 → 复制 Identifier。
  • Finder（macOS Catalina 及以上）：连接设备 → 在 Finder 侧边栏选中设备 → 点击设备信息区域可显示 UDID。
  • 设置 App / TestFlight：部分第三方工具或 TestFlight 也可获取。

旧版文档中通过 iTunes 获取 UDID 的方式已不适用，请使用上述方法。

10. 创建描述文件（Provisioning Profile）

描述文件将 App ID、证书和设备 绑定在一起，是真机调试和应用分发必不可少的文件。

10.1 开发描述文件（Development）

  1. 左侧选择 Profiles，点击 +。
  2. 选择 iOS App Development，点击 Continue。
  3. 选择已创建的 App ID，点击 Continue。
  4. 选择需要绑定的 开发证书（建议勾选 Select All），点击 Continue。
  5. 选择授权调试的 设备（建议勾选 Select All），点击 Continue。
  6. 输入描述文件名称，点击 Generate。
  7. 点击 Download 下载 .mobileprovision 文件。

10.2 发布描述文件（App Store）

  1. 点击 +，选择 App Store，点击 Continue。
  2. 选择 App ID，点击 Continue。
  3. 选择 iOS Distribution / Apple Distribution 发布证书，点击 Continue。
  4. 输入描述文件名称，点击 Generate → Download。

10.3 Ad Hoc 描述文件（内测分发，可选）

若需向指定设备分发内测包（不经过 App Store）：

  1. 点击 +，选择 Ad Hoc，点击 Continue。
  2. 选择 App ID、发布证书、已注册的 测试设备。
  3. 生成并下载 .mobileprovision 文件。
  4. 使用发布 P12 + Ad Hoc 描述文件云打包，通过 TestFlight、蒲公英等平台分发。

10.4 安装描述文件

  • 双击 .mobileprovision 文件，系统会自动安装到 Xcode。
  • HBuilderX 云打包时，需在打包界面分别上传 开发/发布证书（.p12） 和对应 描述文件（.mobileprovision）。

11. 导出 P12 证书

P12 格式证书包含公钥和私钥，用于 HBuilderX 云打包、Unity 等第三方打包工具进行代码签名。

  1. 在钥匙串访问中找到已安装的证书（Apple Development 或 Apple Distribution）。
  2. 展开证书，确认下方有关联的私钥（若无私钥，说明 CSR 与当前 Mac 不匹配，需重新生成 CSR 并申请证书）。
  3. 右键点击证书 → 导出「Apple Development: 姓名 (邮箱)」（或 Distribution 证书）。
  4. 文件格式选择 个人信息交换 (.p12)，选择保存路径。
  5. 设置 证书密码（打包签名时需要，请务必牢记）。
  6. 输入 Mac 系统密码，完成导出。

重要：P12 证书包含私钥，请妥善保管，切勿分享给他人或提交到公开仓库。

12. HBuilderX 云打包与 Xcode 配置

12.1 HBuilderX 云打包（推荐）

  1. 用 HBuilderX 打开工程：vortmall-uniapp/。
  2. 点击 发行 → 原生 App-云打包 → iOS。
  3. 在云打包配置中填写/选择：
    • Bundle ID：与 App ID 的 Bundle ID 一致
    • 证书：上传 .p12 并填写导出密码
    • 描述文件：选择对应的 .mobileprovision
    • 图标、启动图：按需配置
  4. 选择打包类型（开发包 / 正式包），提交云打包。
  5. 打包完成后下载 .ipa 或 iOS 工程文件。

证书与打包类型对应：

打包目的证书描述文件
真机调试开发 P12iOS App Development
Ad Hoc 内测发布 P12Ad Hoc
App Store 上架发布 P12App Store

12.2 本地 Xcode 工程（可选）

若需本地调试或自定义原生配置：

  1. 通过 HBuilderX 云打包下载 iOS 原生工程，或使用 发行 → 原生 App-本地打包 生成工程。
  2. 在 Mac 上用 Xcode 打开工程。
  3. 选择项目 → Signing & Capabilities：
    • 使用 Apple ID 登录并选择 Team。
    • 配置 Bundle Identifier（与 manifest.json 一致）。
    • 选择或导入 Provisioning Profile。

简化方式：Xcode 可开启 Automatically manage signing，自动创建证书与描述文件，适合个人开发者快速调试；正式上架仍建议使用手动管理的发布证书。

13. 测试应用

13.1 模拟器测试

在 Xcode 中选择模拟器设备，点击 Run（▶） 运行测试。

13.2 真机测试

  1. 用数据线连接 iOS 设备，并在设备上信任此电脑。
  2. 使用开发证书 + 开发描述文件云打包得到的 .ipa，安装到已加入 Devices 的测试设备。
  3. 或在 Xcode 顶部选择物理设备，点击 Run 直接运行。
  4. 首次安装可能需在设备 设置 → 通用 → VPN 与设备管理 中信任开发者证书。

更多真机调试细节参见 VortMall · iOS 真机调试配置。

13.3 Ad Hoc 内测

使用 Ad Hoc 描述文件打包的 .ipa，可通过 TestFlight、蒲公英等分发平台安装到已注册 UDID 的设备上。

13.4 VortMall 功能验证建议

  • 登录/注册、商品浏览、下单、支付（支付宝）流程正常
  • 定位附近门店、相机/相册权限弹窗文案正确
  • API 接口指向 .env.production 配置的生产地址
  • IM 聊天、消息推送（若启用 MQTT）可正常接收

14. 发布到 App Store

14.1 在 App Store Connect 创建应用

  1. 登录 App Store Connect。
  2. 点击 我的 App → +，创建新 App。
  3. 填写应用名称、语言、类别、Bundle ID、隐私政策 URL 等必填信息。
  4. 准备上架所需的截图、描述、关键词等市场信息。

14.2 上传应用包

方式一：Xcode Archive（本地工程）

  1. 使用 HBuilderX 生成 iOS 原生工程，在 Xcode 中打开。
  2. Xcode 中选择 Product → Archive。
  3. Archive 完成后，点击 Distribute App。
  4. 选择 App Store Connect 作为发布目标，按向导完成上传。

方式二：HBuilderX 云打包 + Transporter（推荐）

  1. 使用 App Store 发布描述文件 + 发布 P12 云打包生成 .ipa。
  2. 通过 Mac 上的 Transporter App 或 xcrun altool 上传至 App Store Connect。

14.3 提交审核

  1. 在 App Store Connect 中填写应用截图、描述、关键词、分级等信息。
  2. 选择刚上传的构建版本。
  3. 提交审核，等待苹果审核（通常 1–3 个工作日）。

审核通过后，应用即可在 App Store 上线。

15. 常见问题

证书相关

问题处理方式
证书过期证书有效期 1 年，过期前按第 8 节重新申请；已上架 App 不受影响，更新版本时需使用新证书
证书数量超限个人账号最多 2 个开发证书、1 个发布证书；删除过期证书可释放名额
换了新 Mac从旧 Mac 导出 P12 证书，在新 Mac 上安装 P12 及对应描述文件
证书不受信任检查系统时间、重新下载 Apple 根证书、确认 CSR 与证书匹配
P12 密码忘记无法恢复，需重新申请证书并重新导出 P12
导出 P12 无私钥CSR 与当前 Mac 不匹配，需在同一台 Mac 重新生成 CSR 并申请证书

打包与上传

问题处理方式
Bundle ID 不一致确保 manifest.json 包名、App ID、描述文件三者 Bundle ID 完全一致
描述文件与证书不匹配重新生成描述文件，确保选择了正确的证书类型
上传失败更新 Xcode 至最新版，检查网络，确认使用 Distribution 证书 + App Store 描述文件
云打包失败核对 P12 密码、描述文件类型（开发/发布/Ad Hoc）是否与打包类型一致
图标路径错误改为项目内相对路径，勿用本机绝对路径
接口不可用确认 VITE_API_URL 为 HTTPS 且可公网访问

审核相关

问题处理方式
审核被拒查看 App Store Connect 中的拒绝原因，修改后重新提交
隐私政策缺失App Store Connect 必须填写有效的隐私政策 URL
权限说明不完整在 manifest.json 的 privacyDescription 中补充各权限的使用说明（如相机、定位等）

推送证书（可选）

若 VortMall 启用 IM 消息推送：

  1. 在 App ID 中勾选 Push Notifications 服务。
  2. 在 Certificates 页面申请 APNs Development iOS 或 APNs Distribution iOS。
  3. 上传 CSR 生成推送证书，导出为 P12 供服务端使用。
  4. .env.production 配置 VITE_MQTT_URL（生产环境须使用 wss://）。
  • ©2026 VortMall Baishang Technology (Group)
iOS APP 发布与证书申请指南
Enter search text
HomeDocumentation center
Outline
VortMall iOS APP 发布与证书申请指南
本文档介绍如何将 VortMall 开源商城 UniApp 端（vortmall-uniapp/）打包并发布到 iOS 平台，涵盖证书申请、云打包、真机测试与 App Store 上架全流程。
目录
1. 前置准备
2. 配置生产环境变量
VortMall 项目完整变量说明
3. 配置 manifest.json
3.1 VortMall 当前预置配置参考
3.2 iOS 图标配置注意
4. 注册 Apple 开发者账号
5. 证书类型说明
6. 生成 CSR 证书签名请求
6.1 打开钥匙串访问
6.2 创建 CSR 文件
7. 创建 App ID
7.1 进入标识符管理
7.2 填写 App ID 信息
8. 申请开发与发布证书
8.1 登录开发者平台
8.2 申请开发证书（Apple Development）
8.3 申请发布证书（Apple Distribution）
8.4 安装证书到钥匙串
9. 添加调试设备
10. 创建描述文件（Provisioning Profile）
10.1 开发描述文件（Development）
10.2 发布描述文件（App Store）
10.3 Ad Hoc 描述文件（内测分发，可选）
10.4 安装描述文件
11. 导出 P12 证书
12. HBuilderX 云打包与 Xcode 配置
12.1 HBuilderX 云打包（推荐）
12.2 本地 Xcode 工程（可选）
13. 测试应用
13.1 模拟器测试
13.2 真机测试
13.3 Ad Hoc 内测
13.4 VortMall 功能验证建议
14. 发布到 App Store
14.1 在 App Store Connect 创建应用
14.2 上传应用包
14.3 提交审核
15. 常见问题
证书相关
打包与上传
审核相关
推送证书（可选）