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

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

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

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

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

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

文章目录

• • 前言
  • 为什么需要 manifest.plist，它做了什么
  • manifest.plist 示例与字段解析（逐项说明）
  • 手工生成 manifest.plist（简单场景）
  • 可运行 Demo：用 Python 自动生成 manifest.plist（推荐）
  • 在 CI 中自动打包导出 .ipa（xcodebuild 示例）
  • 托管 manifest.plist 与 ipa：生产环境建议（S3 / nginx 示例）
  • 安装流程（最终用户体验）
  • 常见问题与排查思路
  • 安全与合规提醒（重要）
  • 总结

前言

最近在给同事讲企业签名分发流程时，发现很多人卡在一个点上：如何正确生成 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，确认能访问；
• 最后，企业签名合规问题不能忽视：证书管理、使用范围、风险应对都要有流程。