apple-ship

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shipping Darwin Apps

发布 Darwin 应用

Use this for any work that builds or ships an app targeting iOS or macOS, regardless of the source language (native Swift/ObjC, Wails, Tauri, Electron, Go, Rust). This is the routing hub: it tells you which reference doc to read based on what is in the repo and what you are doing.
对于任何以 iOS 或 macOS 为目标的应用构建或发布工作,无论源代码语言是什么(原生 Swift/ObjC、Wails、Tauri、Electron、Go、Rust),均应使用本文档。它是路由枢纽:会根据仓库中的内容和当前任务,告诉你应阅读哪份参考文档。

Guardrails

安全守则

  • Keep private keys,
    .p8
    files, certificates, provisioning profiles, and
    .p12
    files out of chat, logs, and git; they reach CI only as encrypted repository secrets. Keep
    .xcarchive
    ,
    .ipa
    ,
    .dmg
    , and exported app bundles out of git and chat; they leave the machine only through the release workflow's upload and artifact steps.
  • Never print certificate passwords, app-specific passwords, API keys, base64 certificate payloads, temporary keychain passwords, or notarization credentials.
  • Get explicit approval before submitting to App Store review, publishing publicly, changing bundle identifiers, rotating credentials, or altering account/team settings. Internal TestFlight upload may proceed only when the user authorized release automation.
  • Treat Apple Developer Team IDs, bundle IDs, and App Store Connect app IDs as project configuration. Do not hard-code personal examples into public docs.
  • Check
    git status
    before touching unrelated workflow, signing, version, or project changes.
  • If a signing identity's private key is missing, stop. A certificate alone cannot produce a usable signature.
  • 不要将 private keys、
    .p8
    files、certificates、provisioning profiles 和
    .p12
    files 放入聊天、日志或 git;它们只能以加密的 repository secrets 形式进入 CI。同样,不要将
    .xcarchive
    、
    .ipa
    、
    .dmg
    和导出的 app bundles 放入 git 或聊天;这些文件只能通过发布 workflow 的上传和 artifact 步骤离开本机。
  • 绝不输出 certificate passwords、app-specific passwords、API keys、base64 certificate payloads、temporary keychain passwords 或 notarization credentials。
  • 在提交 App Store 审核、公开发布、修改 bundle identifiers、轮换 credentials 或更改 account/team settings 之前,必须获得明确批准。只有在用户已授权 release automation 时,内部 TestFlight 上传才可继续进行。
  • 将 Apple Developer Team IDs、bundle IDs 和 App Store Connect app IDs 视为项目配置。不要在公开文档中硬编码个人示例。
  • 在修改无关的 workflow、签名、版本或项目配置前,检查
    git status
    。
  • 如果缺少某个 signing identity 的 private key,则停止操作。仅有 certificate 无法生成可用签名。

Route to the right doc

路由到正确的文档

Read only what you need. Start here, then open the doc the repo signal points to.
If the environment is uncertain, or this is a project's first release, start with readiness.md to understand what is checked and installed.
Detect the build doc from the repo:
Repo signalRead
.xcodeproj
/
.xcworkspace
/
project.yml
/
Package.swift
build/native.md
wails.json
or Wails in
go.mod
build/wails.md
tauri.conf.json
build/tauri.md
package.json
with electron / electron-builder
build/electron.md
go.mod
/
Cargo.toml
producing a
.app
/
.dmg
build/go-rust.md
Detect the ship doc from the distribution target:
Distribution targetRead
iOS via App Store / TestFlightship/appstore.md
macOS outside the App Store (Developer ID, notarization)ship/direct.md
Only ask the human when the repo cannot answer it: is this release or debug? which distribution channel? real release or dry run? Use repo signals for everything else.
只阅读所需内容。从这里开始,然后打开 repo signal 指向的文档。
**如果环境不确定,或这是项目的首次发布,**先阅读 readiness.md,了解需要检查和安装的内容。
根据仓库信号检测构建文档:
仓库信号阅读
.xcodeproj
/
.xcworkspace
/
project.yml
/
Package.swift
build/native.md
wails.json
或
go.mod
中的 Wails
build/wails.md
tauri.conf.json
build/tauri.md
包含 electron / electron-builder 的
package.json
build/electron.md
生成
.app
/
.dmg
的
go.mod
/
Cargo.toml
build/go-rust.md
根据分发目标检测发布文档:
分发目标阅读
通过 App Store / TestFlight 发布 iOSship/appstore.md
App Store 之外的 macOS(Developer ID、notarization)ship/direct.md
**仅当仓库无法回答以下问题时才询问用户:**这是 release 还是 debug?使用哪个 distribution channel?是正式发布还是 dry run?其他所有信息都应通过 repo signals 获取。

Quick reference

快速参考

What you are doingNecessary command
Build a native Xcode app
xcodebuild archive -scheme <scheme> -archivePath <path>
Build a Wails app
wails3 build
/
task package:<os>
Build a Tauri app
npm run tauri build
Build an Electron app
npx electron-builder --mac
Sign (Developer ID)
codesign --force --options runtime --timestamp --sign "<identity>" <app>
Notarize
xcrun notarytool submit <file> --apple-id ... --team-id ... --password ... --wait
Staple + verify
xcrun stapler staple <file>; xcrun stapler validate <file>
Gatekeeper assess (app/DMG)
spctl --assess --type execute --verbose=4 <app>
/
--type open --context context:primary-signature <dmg>
Cross-reference: reusable
workflow_call
contracts live in the
gh-workflows
skill in the
vuon9/gh-workflows
repo.
当前任务必要命令
构建原生 Xcode 应用
xcodebuild archive -scheme <scheme> -archivePath <path>
构建 Wails 应用
wails3 build
/
task package:<os>
构建 Tauri 应用
npm run tauri build
构建 Electron 应用
npx electron-builder --mac
签名(Developer ID)
codesign --force --options runtime --timestamp --sign "<identity>" <app>
公证
xcrun notarytool submit <file> --apple-id ... --team-id ... --password ... --wait
Staple + 验证
xcrun stapler staple <file>; xcrun stapler validate <file>
Gatekeeper 评估(app/DMG)
spctl --assess --type execute --verbose=4 <app>
/
--type open --context context:primary-signature <dmg>
交叉参考:可复用的
workflow_call
合约位于
vuon9/gh-workflows
仓库的
gh-workflows
skill 中。