macOS 适配 runbook（在 Mac 上执行）

August 23, 2026 · View on GitHub

目标：产出 DSH_Shell macOS 自包含便携包（dist/DSH_Shell_<ver>_universal-macos.zip）。 通用二进制 + 双架构 darwin Node/dsh 依赖树，运行时按主机架构自动选择；Windows 侧代码已跨平台化（本次不在 Windows 上验证 mac 链路）。

0. 前置

  • Xcode Command Line Tools 
    xcode-select --install
  • Rust + mac 目标 
    rustup target add aarch64-apple-darwin x86_64-apple-darwin
  • Node / pnpm：node -v、pnpm -v 可用。

1. 生成 darwin 版 harness 依赖树

dsh/ 内含平台绑定的原生依赖（node-pty/sharp/koffi/node-addon-require-builtin-*），必须在 Mac 上安装出身匹配的 darwin 版本。

  • 单架构（先选你机器架构，或按需分别构建）：

    cd dsh && pnpm install --prod

    产物为 dsh/node_modules（宿主机 darwin 版）。

  • universal（推荐）：需要 arm64 与 x64 两套依赖树。分别用 dsh-arm64/ 与 dsh-x64/ 存放（各自 pnpm install --prod），供打包脚本读取：

    mkdir -p dsh-arm64 dsh-x64
# 在任一 Mac 上，用 arm64 的 node 装一份到 dsh-arm64；用 x64 的 node 装一份到 dsh-x64
# 例：arm64 机器装完拷贝 → dsh-arm64；x64 机器装完拷贝 → dsh-x64

注：pnpm 会在 dsh/node_modules 里放 .pnpm 目录与 dir-links。为减小体积可 pnpm install --prod 后平铺（与 Windows 便携一致）。默认平铺时脚本不再额外展开。

2. 准备 Node 运行时二进制

Node 官方不提供 darwin 通用二进制（node 按架构分 -arm64/-x64）。打包脚本需要：

  • --node-dir <dir>：目录内含 node-arm64、node-x64（或单架构的 node）。
  • 或 --download-node：脚本自动从 nodejs.org 下载 v22.14.0 的 darwin-arm64 / darwin-x64。
  • 或直接用 PATH 的 node（仅单架构）。

3. 打包

在仓库根执行：

chmod +x scripts/package-portable.sh
# universal（推荐）
./scripts/package-portable.sh --arch universal --node-dir "$HOME/Downloads/nodes" --download-node
# 或单架构
./scripts/package-portable.sh --arch arm64

产物：dist/DSH_Shell_0.1.0_universal-macos.zip。

4. 验证

mkdir -p /tmp/dsh-mac && cd /tmp/dsh-mac
unzip -q ~/path/to/DSH_Shell_0.1.0_universal-macos.zip
# 首次运行：弹窗选择数据目录（默认程序目录下 .dsh）
./DSH_Shell
# 期望：拉起 harness（http://127.0.0.1:<port>）并打开窗口；托盘图标可按深浅主题切换

5. 常见排查

  • tauri build 报 target aarch64-apple-darwin not found：rustup target add aarch64-apple-darwin 并确认 xcode-select -p 指向 CLT。
  • lipo / Mach-O 报错：确认两个 triple 都构建成功，二进制不以 .exe/文本形式存在。
  • 首启下载失败：检查包内是否含 npm/node_modules/npm；无则回退系统 npm，需本机已装 node。
  • Gatekeeper / quarantine：从网上下载的 zip 可能被 macOS 拦截，需 xattr -dr com.apple.quarantine /tmp/dsh-mac 或右键打开。生产分发建议签名/公证（本次未做）。