在企业内部分发 iOS App 时如何生成并使用 manifest.plist

发布于：2025-09-11 ⋅ 阅读:(22) ⋅ 点赞:(0)

网罗开发 （小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！


文章目录

前言

最近在给同事讲企业签名分发流程时，发现很多人卡在一个点上：如何正确生成 manifest.plist 并把它和 .ipa 一起托管，让同事或测试设备通过 itms-services 一键安装。本文把完整思路、常见坑、生产环境注意点都聊清楚，并给出一个可运行的 Python Demo，可以直接用来生成 manifest.plist。

写得尽量口语化、接近日常工作交流；每一部分都尽量讲清楚“为什么要这么做”以及“怎么做”，并配上示例。

为什么需要 manifest.plist，它做了什么

iOS 的企业内部分发（Enterprise Distribution）通过一个特殊的 URL 协议 itms-services://?action=download-manifest&url=<manifest_url> 触发安装。系统读取你提供的 manifest.plist 来知道要下载哪一个 .ipa，以及这个应用的 bundle identifier、版本、名称等元信息。

换句话说，manifest.plist 是安装器的“导航文件”——iOS 不是直接下载 .ipa，而是先下载并解析 plist，然后据此去拿 .ipa。另外必须满足两点：

  • manifest.plist 和 ipa 都必须通过 HTTPS 提供（真实有效的证书）；
  • manifest.plist 的结构和字段要准确，否则 iOS 会报错或不安装。

生产环境最容易忽略的点就是：HTTPS 必须是真实可信的 CA 证书（自签名/不信任证书在 iOS 上通常无法安装应用），以及 manifest 的 URL 必须可访问且返回正确的 Content-Type。下面细讲结构与示例。

manifest.plist 示例与字段解析（逐项说明）

这是一个最常见的 manifest.plist（把你的 ipa 地址、bundle id 等替换为真实值）：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>items</key>
  <array>
    <dict>
      <key>assets</key>
      <array>
        <dict>
          <key>kind</key>
          <string>software-package</string>
          <key>url</key>
          <string>https://yourserver.com/path/to/app.ipa</string>
        </dict>
      </array>
      <key>metadata</key>
      <dict>
        <key>bundle-identifier</key>
        <string>com.company.app</string>
        <key>bundle-version</key>
        <string>1.0.0</string>
        <key>kind</key>
        <string>software</string>
        <key>title</key>
        <string>CompanyApp</string>
      </dict>
    </dict>
  </array>
</dict>
</plist>

字段说明（很重要）：

  • items：根数组，通常只放一条描述一个 app。
  • assets → kind: software-package：表示这是一个应用包；
  • assets → url：指向 .ipa 的 HTTPS 地址（必须能通过浏览器直接访问并用有效证书）；
  • metadata → bundle-identifier：要跟你应用的 Bundle Identifier 一致（Xcode 中的那个）；
  • metadata → bundle-version：App 的版本号（CFBundleShortVersionString）；
  • metadata → title：在安装对话框里显示的应用名字。

如果某个字段错了（比如 bundle id 不一致、或者 ipa 地址不可达），iOS 会提示“无法安装”或“无法检索清单”。

手工生成 manifest.plist（简单场景）

你可以直接按上面的模板把 manifest.plist 写好，保存为 manifest.plist，上传到 HTTPS 可访问的服务器上，然后用如下链接触发安装：

itms-services://?action=download-manifest&url=https://yourserver.com/manifest.plist

如果想方便点，可以把上述链接做成页面上的按钮或二维码，用户用 Safari 打开后就会提示安装。

但手写容易出错，建议用脚本自动生成（下面有可运行 Demo）。

可运行 Demo：用 Python 自动生成 manifest.plist（推荐）

下面是一个小脚本，能把你传入的参数写成合规的 manifest.plist。用 Python 的 plistlib 来生成，少出错。保存为 gen_manifest.py。

#!/usr/bin/env python3
"""
gen_manifest.py
生成 manifest.plist 的小工具。

用法示例:
python3 gen_manifest.py \
  --ipa-url https://example.com/builds/app.ipa \
  --bundle-id com.company.app \
  --version 1.2.3 \
  --title "Company App" \
  --output manifest.plist
"""

import argparse
import plistlib
import sys
from pathlib import Path

def build_manifest(ipa_url: str, bundle_id: str, version: str, title: str):
    manifest = {
        "items": [
            {
                "assets": [
                    {
                        "kind": "software-package",
                        "url": ipa_url
                    }
                ],
                "metadata": {
                    "bundle-identifier": bundle_id,
                    "bundle-version": version,
                    "kind": "software",
                    "title": title
                }
            }
        ]
    }
    return manifest

def main():
    parser = argparse.ArgumentParser(description="Generate manifest.plist for iOS enterprise distribution")
    parser.add_argument("--ipa-url", required=True, help="Public HTTPS URL to the .ipa")
    parser.add_argument("--bundle-id", required=True, help="Bundle identifier, e.g. com.company.app")
    parser.add_argument("--version", required=True, help="App version, e.g. 1.0.0")
    parser.add_argument("--title", required=True, help="App title shown during install")
    parser.add_argument("--output", default="manifest.plist", help="Output plist filename")
    args = parser.parse_args()

    manifest = build_manifest(args.ipa_url, args.bundle_id, args.version, args.title)
    out_path = Path(args.output)
    with out_path.open("wb") as f:
        plistlib.dump(manifest, f)
    print(f"Generated {out_path.resolve()}")

if __name__ == "__main__":
    main()

说明与使用示例：

  1. 把 gen_manifest.py 放到你的机器上，确保 Python 3 可用；

  2. 执行（替换 URL、bundle id、版本、title）：

    python3 gen_manifest.py \
  --ipa-url https://cdn.example.com/apps/app-1.2.3.ipa \
  --bundle-id com.example.myapp \
  --version 1.2.3 \
  --title "Example App" \
  --output manifest.plist

  3. 脚本会生成 manifest.plist，上传该文件与对应 .ipa 到你的 HTTPS 可访问服务器后，用 itms-services://... 链接测试安装。

这个脚本足够轻量，也方便你把它嵌入 CI：在 CI 打包出 .ipa 并上传到 S3 或公司内网后，CI 调用此脚本生成 manifest 并上传，最后把安装链接发给 QA。

在 CI 中自动打包导出 .ipa（xcodebuild 示例）

如果你想在 CI 中自动从 Xcode archive 导出 enterprise .ipa，可以用 xcodebuild -exportArchive 配合一个 exportOptions.plist，示例如下。

exportOptions.plist（保存为 XML plist）主要关键字段是 method = enterprise，并指定 provisioning profile：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>enterprise</string>
  <key>teamID</key>
  <string>YOUR_TEAM_ID</string>
  <key>provisioningProfiles</key>
  <dict>
    <key>com.example.myapp</key>
    <string>My Enterprise Provisioning Profile Name</string>
  </dict>
</dict>
</plist>

然后在机器上运行（假设已用 xcodebuild archive 得到 MyApp.xcarchive）：

xcodebuild -exportArchive \
  -archivePath /path/to/MyApp.xcarchive \
  -exportOptionsPlist /path/to/exportOptions.plist \
  -exportPath /path/to/output_dir

导出后 output_dir 下会有 .ipa，把它上传到 HTTPS 托管后，再生成 manifest。

如果你使用 Fastlane，在 Fastfile 里用 gym/sigh 帮助自动化也很常见。

托管 manifest.plist 与 ipa：生产环境建议（S3 / nginx 示例）

无论你把文件放哪里，两个硬性条件必须满足：

  1. 访问地址是 HTTPS（有效证书）；
  2. manifest.plist 与 .ipa 的 Content-Type 设置合理，方便调试时确认。

示例：用 AWS S3 + CloudFront（常见、稳定）

# 上传 ipa，指定 Content-Type
aws s3 cp app.ipa s3://my-bucket/path/app-1.2.3.ipa --acl public-read --content-type application/octet-stream

# 上传 manifest
aws s3 cp manifest.plist s3://my-bucket/path/manifest.plist --acl public-read --content-type application/xml

然后通过 CloudFront 或自定义域名配 TLS（ACM）暴露 https://dl.company.com/path/manifest.plist，拼装 itms-services 链接。

如果你用 nginx 自建分发，注意 server 配置示例（关键点：设置 MIME，HTTPS）：

server {
    listen 443 ssl;
    server_name dl.company.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location /apps/ {
        root /var/www;
        # 强制使用正确 content-type（可选）
        types {
            application/octet-stream ipa;
            application/xml plist;
        }
        add_header Cache-Control "max-age=3600";
    }
}

注意事项：

  • manifest.plist 的 Content-Type 用 application/xml 或 text/xml 都没问题；
  • .ipa 推荐 application/octet-stream；
  • 一定要用真实 CA 证书，iOS 设备对不受信任证书会拒绝安装。

安装流程（最终用户体验）

  1. 用户在 iOS 设备的 Safari 打开如下链接（通常是放在网页里的按钮或二维码）：

    itms-services://?action=download-manifest&url=https://dl.company.com/path/manifest.plist

  2. Safari 会跳转到系统安装对话框，用户确认后系统开始下载并安装。

  3. 第一次在该设备上用该企业证书安装后，用户需要在 设置 → 通用 → 描述文件与设备管理（或“设备管理”）里手动“信任”企业证书（部分 iOS 版本会在安装时同时提示），这是 iOS 的安全策略。

在企业内测场景中，最好有一份安装说明告诉用户如何信任证书。

常见问题与排查思路

  • iOS 显示“无法安装/未能检索清单”：

    • 检查 manifest.plist 是否可通过 HTTPS 访问（手机能直接打开）；
    • 检查 manifest 的根节点、字段是否完整（bundle id、bundle version、url）且无语法错误；
    • 检查 ipa URL 是否返回 200，并且不是返回 HTML 页面或 302 跳转（iOS 可能不跟重定向）；
    • 检查 HTTPS 证书是否受信任（生产必须使用受信任 CA 证书）；
    • 检查 bundle id 是否与 ipa 内的匹配（比如你签名时用的描述文件/证书是否对应该 bundle id）。

  • 安装完成但 App 打不开/闪退：

    • 检查企业签名是否包含私钥并且没有被撤销；
    • 检查 Provisioning Profile 是否包含所用证书/正确的 entitlements；
    • 查看设备 log（通过 Xcode 的 Devices 窗口）查看崩溃或签名错误信息。

  • 企业证书被吊销导致无法安装：

    • 定期审计证书使用，避免滥用；若被吊销，需尽快重新申请企业证书并重新打包分发。

安全与合规提醒（重要）

  • Apple 对企业签名分发管控严格，企业账号仅允许企业内部分发给公司员工和受管控的设备，不得对外公开分发给任意用户；滥用可能导致证书被吊销。
  • 在公司内部分发时，记录好每次分发的版本、时间和接收方，便于追踪。建议结合 MDM（移动设备管理）来统一管理应用/设备。
  • 证书与私钥需要被妥善保管，CI 系统中的私钥导入需做好权限隔离与密钥周期更换策略。

总结

  • manifest.plist 是 iOS 企业内部分发的关键导航文件，必须通过 HTTPS 提供且格式正确；
  • 推荐用脚本自动化生成 manifest（示例提供了 Python 脚本），把生成过程放入 CI 流水线；
  • 生产环境要保证 .ipa 与 manifest.plist 都托管在 HTTPS（可信）地址上，推送时注意正确的 Content-Type；
  • 测试安装前，先用 iOS 设备在 Safari 里打开 manifest.plist 的 URL，确认能访问；
  • 最后，企业签名合规问题不能忽视：证书管理、使用范围、风险应对都要有流程。

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布