docs: record the macOS packaging scheme next to the artifacts

The ad-hoc signature, the two containers and their different jobs, and how to
verify a download were explained only in docs/RELEASE.md. A user who downloads
Shift-macOS-universal.pkg from the releases branch never sees that file, so the
same write-up now also ships as artifacts/README-macOS-universal.txt, beside the
per-arch Windows notes that already travelled with the channel.

Every claim was checked against the shipped artifacts rather than carried over:
the .pkg payload is Signature=adhoc, pkgutil --check-signature reports no
signature for the package itself, and shasum -c passes on the published set. The
file is force-added to the repository even though artifacts/ is gitignored, so
the scheme is documented where a contributor reads it.
main
mula.liu 2026-10-26 10:40:33 +08:00
parent 4ed236bd9e
commit f2a1ff6d52
2 changed files with 125 additions and 4 deletions

View File

@ -0,0 +1,113 @@
Shift 0.1.3 - macOS 通用(universal)
本文件说明 macOS 安装包是怎么打出来的、两个安装包各自负责什么、在其它机器上
会遇到什么,以及如何自己校验。完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。
为什么有两个安装包
------------------
本项目的构建是 ad-hoc 签名(src-tauri/tauri.conf.json 里 signingIdentity 固定为
"-"),且没有 Apple Developer ID 可做公证。Gatekeeper 因此无法为任何 Shift 构建背书,
一台新机器上的表现取决于安装包的形式:
| 安装包 | 用途 | 新机器上的表现 |
| --- | --- | --- |
| Shift-macOS-universal.pkg | 首次安装,交给任何新机器 | installer 不会把隔离属性带给装好的应用,装好后打开**完全没有提示**。已实测:装好的副本只带 com.apple.provenance,没有 com.apple.quarantine。 |
| Shift-macOS-universal.dmg | 软件内升级通道(清单里的 macos 键) | 应用自己下载的副本不带隔离属性,所以软件内升级也不弹窗。若是从浏览器下载再拖进 /Applications,首次打开需要允许一次。 |
所以:新机器装 .pkg,已在用的 Shift 走软件内升级(下载的是 .dmg)。清单的 macos
键必须是 .dmg —— 软件内升级的交接脚本用 hdiutil 挂载镜像再取出应用包,指向 .pkg
会让每次升级都挂载失败。
pkg 里的应用与被拖出来的应用是同一份签名:pkgbuild 既不重新签名也不剥离签名,
内置应用、DMG 内副本、pkg 内副本的 CDHash 完全一致(已核对)。
在其它机器上安装
----------------
安装包 .pkg(推荐,新机器)
1. 下载 Shift-macOS-universal.pkg。pkg 本身没有签名(productsign 需要一枚带
Installer Signing 用途的证书,本项目只有代码签名身份),因此浏览器下载后
双击可能被拦:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」,
只需一次,发生在安装之前。
2. 之后按提示安装,载荷会落到 /Applications。
3. 启动 Shift,不会再有任何 Gatekeeper 提示。
终端安装连这一次都不需要:
sudo installer -pkg Shift-macOS-universal.pkg -target /
磁盘镜像 .dmg(新机器,或想手动装)
1. 双击挂载,把 Shift.app 拖进 /Applications。
2. 首次启动被拦:「无法打开,因为来自身份不明的开发者」。点取消后,右键
Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。
3. 只需允许一次,之后再打开正常。
macOS 权限
截图与录屏需要「屏幕录制」,输出目录需要「文件与文件夹」,带声音录屏需要
「麦克风」。Shift 会在打开截图遮罩前先检查屏幕录制权限,被拒绝时给的是可操作
的提示,而不是一张全黑截图。
注意:ad-hoc 构建每次的代码签名哈希都不同,而 macOS 把「屏幕录制」这类授权绑在
这个哈希上,所以一次升级后可能需要重新授权——这与手动重装是同一后果。要彻底消除
它,需要 Developer ID 证书加公证(见仓库 docs/ROADMAP.md 的 M5)。
软件内升级
设置 → 软件更新 里检查并安装:Shift 自己下载 .dmg,先核对字节数与 SHA256,
再由一个独立脚本等本进程退出后挂载镜像、ditto 出新副本、去掉隔离属性、用两次
mv 换上新版本并重新打开。下载不走浏览器,新副本不带隔离属性,所以这一步没有任何
Gatekeeper 提示。
如何自己构建
------------
构建机需先装好两个 Rust 目标,以及 macOS 侧的原生伴生进程(AppKit 拖拽桥、PDFKit
与文档渲染,会被打成通用二进制):
rustup target add aarch64-apple-darwin x86_64-apple-darwin
pnpm install
pnpm mac:drag-bridge
生成通用应用与 DMG,再把应用包包成 .pkg:
pnpm tauri build --target universal-apple-darwin --bundles app,dmg
scripts/macos-pkg.sh \
src-tauri/target/universal-apple-darwin/release/bundle/macos/Shift.app \
artifacts/Shift-macOS-universal.pkg
scripts/macos-pkg.sh 把应用包暂存到一个 /Applications 根目录下,再用 pkgbuild 打包;
install-location 指向 /Applications,所以这台机器上的每个用户都会装到那里。它用
ditto 而不是 cp,以保留资源分支、符号链接与代码签名。
若希望更新通道能校验来源,构建时把 ed25519 公钥编进去(发布流程见仓库
docs/RELEASE.md 的「Signing the channel」):
export SHIFT_RELEASE_KEY=~/.config/shift-release/release.ed25519
export SHIFT_UPDATE_PUBKEY=$(python3 scripts/release-key.py pubkey \
~/.config/shift-release/release.ed25519)
如何校验
--------
哈希(本目录下的 SHA256SUMS.txt 覆盖所有产物):
shasum -a 256 -c SHA256SUMS.txt
签名形态(adhoc 是当前刻意选择的形式,不是出错):
codesign -dv --verbose=2 /Applications/Shift.app 2>&1 | grep -E 'Signature|Identifier'
# Signature=adhoc
# Identifier=app.nex.shift
安装包本体(pkg 未签名是已知状态,真正的签名在里面的应用上):
pkgutil --check-signature Shift-macOS-universal.pkg # Status: no signature
pkgutil --payload-files Shift-macOS-universal.pkg # ./Shift.app/...
镜像完整性:
hdiutil verify Shift-macOS-universal.dmg
校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并优先使用 .pkg;若坚持用
.dmg,按上面的「在其它机器上安装」处理首次允许。

View File

@ -146,10 +146,18 @@ same Python pass that walks the files produces both.
Recognised installers: `Shift-macOS-universal.dmg` (macOS), `Shift-Setup-<version>-win-x64.exe`
and `Shift-Setup-<version>-win-arm64.exe` (Windows, keys `windows` and `windows-arm64`),
`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the macOS `.pkg`, the portable
ZIPs, `SHA256SUMS.txt`, the `README-Windows-<arch>.txt` notes — travel with the branch and
are downloadable from it, but are not offered as installers by the manifest. The `.pkg`
carries no key on purpose: the `macos` key must stay a DMG so the in-app handoff can mount
it ("macOS packaging"). Dotfiles and an old manifest are skipped.
ZIPs, `SHA256SUMS.txt`, the `README-Windows-<arch>.txt` notes and
`README-macOS-universal.txt` — the packaging note that explains the ad-hoc signature, what a
fresh machine does with each container, and how to verify a download — travel with the
branch and are downloadable from it, but are not offered as installers by the manifest. The
`.pkg` carries no key on purpose: the `macos` key must stay a DMG so the in-app handoff can
mount it ("macOS packaging"). Dotfiles and an old manifest are skipped.
`README-macOS-universal.txt` is tracked in the repository as well as pushed to the channel,
so the scheme is documented where a contributor reads it and not only next to a build
product. Every claim in it was checked against the shipped artifacts: the installed
`.pkg`'s payload is `Signature=adhoc`, `pkgutil --check-signature` reports `no signature`
for the package itself, and `shasum -a 256 -c SHA256SUMS.txt` passes on the published set.
Both Windows architectures come from one command, which cross-compiles each target,
checks the PE machine field of the binary it just built (`0x8664` for x64, `0xAA64` for