企业官网建设流程全解析

• 桌面应用
• 存储

本篇技术指南以Free-NTFS-for-Mac开源仓库中的打包配置说明（docs/09-打包配置说明.md）为核心，结合 package.json、ninja/build.sh 及其 ARM64 备份文件的真实实现，系统讲解 Nigate 在 macOS 上的 Electron 打包体系：包括双架构（x64 / arm64）产物如何生成、Electron 二进制下载失败（EOF/超时）如何用镜像源解决、通用二进制（universal）与独立双包两种分发策略的取舍，以及如何在当前通用配置与历史 ARM64 配置之间切换。读完本文，你将能独立完成 Nigate 的 DMG / ZIP 打包、按架构定向构建，并理解electron-builder底层配置项的实际作用。

一、打包配置全貌：备份文件与"通用版本"的由来

仓库根目录下保留了两份与打包直接相关的备份文件，它们是理解当前配置的关键线索：

• package.json.backup.arm64—— ARM64 版本的package.json配置备份（版本号为 1.4.3）
• ninja/build.sh.backup.arm64—— ARM64 版本的build.sh脚本备份

对比两份文件与当前版本即可还原配置演进过程：

可以看出，"通用版本"是在 ARM64 专属配置基础上扩展出的：既保留了对 Apple Silicon 的完整支持，又补上了 Intel Mac 的 x64 产物与单一 universal 包，使同一个发布流程可以同时覆盖全部 Mac 机型（Intel 与 Apple Silicon），这与项目"supports all Mac models"的定位一致。

二、Electron 下载失败（EOF）的处理：镜像源机制

打包时electron-builder需要从 GitHub 下载对应架构的 Electron 二进制。打 universal 包时更要同时下载 darwin-x64 与 darwin-arm64 两套二进制，在网络不稳定的环境下直连 GitHub 极易出现EOF / 超时中断打包。

仓库通过双层机制默认启用了镜像源：

第一层：package.json中的electronDownload.mirror固化配置（package.json 第 52-55 行）：

"electronDownload": { "cache": ".electron-cache", "mirror": "https://npmmirror.com/mirrors/electron/" }

该配置告诉electron-builder优先从 npmmirror（原淘宝镜像）拉取 Electron 二进制，cache指定项目内的缓存目录，可加速二次打包。

第二层：ninja/build.sh中的环境变量兜底（ninja/build.sh 第 156-162 行）：

# 打通用包（--universal）时需要下载 darwin-x64 / darwin-arm64 两套 Electron， # 在部分网络环境下直连 GitHub 可能会 EOF / 超时，因此这里默认启用镜像。 export ELECTRON_MIRROR="${ELECTRON_MIRROR:-https://npmmirror.com/mirrors/electron/}" # 可选：指定 Electron 缓存目录（加速二次打包） export ELECTRON_CACHE="${ELECTRON_CACHE:-${HOME}/.cache/electron}"

脚本采用${VAR:-默认值}写法：只要你在执行前手动设置了ELECTRON_MIRROR，就以你的设置为准；未设置时才回退到镜像源。如需切回官方 GitHub 源，打包前显式置空即可：

ELECTRON_MIRROR="" pnpm run build:universal

此外脚本还会导出ELECTRON_BUILDER_CACHE="${HOME}/.cache/electron-builder"（第 210 行），让electron-builder把已下载的二进制缓存在用户主目录，二次打包免重复下载。与之配合的是package.json中的"npmRebuild": false，跳过原生依赖重建，进一步缩短打包时间。

三、package.json 中的打包目标配置详解

当前 package.json 的build.mac.target配置为：

"mac": { "category": "public.app-category.utilities", "target": [ { "target": "dmg", "arch": ["x64", "arm64"] }, { "target": "zip", "arch": ["x64", "arm64"] } ], "artifactName": "${productName}-${version}-${arch}.${ext}", "icon": "src/imgs/ico/flash.icns", "hardenedRuntime": true, "gatekeeperAssess": false, "extendInfo": { "NSHighResolutionCapable": true, "NSRequiresAquaSystemAppearance": false } }

逐项解读：

• target数组：声明产物格式与架构的笛卡尔组合。dmg 和 zip 各自同时产出 x64 与 arm64，即一次默认打包会生成4 个文件（每个架构一个 dmg、一个 zip）。
• arch列表["x64", "arm64"]：这是本文主题的核心开关。它让electron-builder为 Intel Mac（x64）和 Apple Silicon（arm64）分别构建独立应用包；而执行--universal时此列表被忽略，改用单一 fat binary。
• artifactName：产物命名模板${productName}-${version}-${arch}.${ext}，实际生成如Nigate-1.4.5-x64.dmg、Nigate-1.4.5-arm64.zip这类可辨识架构的文件名。
• hardenedRuntime: true：启用 macOS 硬化运行时（Hardened Runtime），是 Gatekeeper 公证链路的必备前提。
• gatekeeperAssess: false：跳过 electron-builder 自带的 Gatekeeper 评估步骤，交由用户在安装阶段处理（见第五节说明）。
• extendInfo：写入 Info.plist 的扩展键，NSHighResolutionCapable声明支持高分屏，NSRequiresAquaSystemAppearance: false允许应用不强制跟随系统外观（配合项目内的主题切换功能）。

dmg段则定义了 DMG 的安装窗口布局（package.json 第 97-123 行）：窗口 540×450，应用图标位于 (130, 150)，右侧 (410, 150) 放置指向/Applications的快捷链接，左下角 (130, 270) 放置README.txt使用说明文件——该文件正是打包脚本从docs/README.txt复制而来（见第四节）。

另外build.files列表界定了打进安装包的资源范围（package.json 第 59-69 行）：scripts/**/*、src/html/**/*、src/imgs/**/*、src/locales/**/*、config/**/*、src/ico/**/*、src/docs/**/*、styles.css与package.json，覆盖了编译产物、多语言界面、图标与帮助文档，与项目src/下的实际目录结构一一对应。

四、打包命令全解：pnpm scripts 与 build.sh 参数

4.1 命令速查表

以上 npm scripts 均定义在 package.json 第 18-24 行，内部统一委托给ninja/build.sh并透传参数（如build:universal即./ninja/build.sh --universal）。脚本还额外支持--clean参数，与任意目标组合使用，例如./ninja/build.sh --dmg --arm64表示"清理后只打 arm64 的 DMG"。

4.2 build.sh 内部执行流程

ninja/build.sh 在调用electron-builder之前会按顺序完成一系列前置检查与准备，理解这段流程有助于排查打包失败：

1. 多语言输出：加载ninja/build-lang.sh，依据LANG/LC_ALL环境变量或 macOS 系统语言自动切换中文、日文、英文提示（如LANG=ja bash build.sh可输出日文日志）。
2. 切换项目根目录：PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"，保证无论从哪个目录调用脚本都能正确找到工程文件。
3. 解析参数：--clean/--dmg/--zip/--arm64/--x64/--universal，未知参数仅告警不中断。
4. 清理 dist：指定--clean时删除旧的dist产物目录，避免残留文件混入新包。
5. 准备 DMG 说明文件：将docs/README.txt复制为根目录README.txt（dmg 配置中引用的正是它），打包完成后脚本会再次清理该临时文件。
6. 依赖与编译：node_modules不存在时自动pnpm install；随后执行pnpm run sync-version（同步版本号）、pnpm run build:stylus（编译 Stylus 样式为styles.css）与pnpm run build:ts（TypeScript 编译）。
7. 卸载残留 DMG：cleanup_mounted_dmg函数用hdiutil info+diskutil双手段查找并强制卸载所有挂载中的 Nigate 卷，这是为了避免"上次打包后未卸载的 DMG 导致本次构建冲突"这一 macOS 打包经典问题。
8. 执行 electron-builder：根据TARGET/ARCH变量的组合选择不同命令（详见 4.3）。

4.3 参数组合与底层 electron-builder 命令

脚本按"格式 × 架构"四种情况分发命令（ninja/build.sh 第 218-254 行）：

• 同时指定格式与架构：如./build.sh --dmg --universal，执行electron-builder --mac dmg --universal；--dmg --arm64则执行electron-builder --mac dmg --arm64。
• 只指定格式：如./build.sh --dmg，按 package.json 的默认 arch 列表（x64 + arm64）执行electron-builder --mac dmg。
• 只指定架构：如--universal执行electron-builder --mac --universal；--arm64/--x64同理。
• 无参数默认打包：为避免并行构建两个架构时 DMG 挂载互相冲突，脚本刻意串行执行——先electron-builder --mac --x64，再electron-builder --mac --arm64，每次构建前都再次调用cleanup_mounted_dmg。这也是默认打包耗时较长、但稳定性较高的原因。

所有 electron-builder 调用前都带有ELECTRON_MIRROR="${ELECTRON_MIRROR:-}"前缀，保证第二节的镜像回退逻辑始终生效。打包结束后脚本会ls -lh dist/列出产物清单，便于核对各架构文件是否齐全。

五、通用二进制与双独立包的取舍

--universal选项与["x64", "arm64"]配置代表了两种不同的分发策略：

• 通用二进制（fat binary）：把 x64 与 arm64 两套可执行代码合并进一个文件。用户无需关心自己的 Mac 是 Intel 还是 Apple Silicon，下载一份即可运行。代价是体积显著增大（两份二进制的内容叠加）。
• 双独立包：生成-x64与-arm64两个独立安装包。每个包体积更小、下载更快，但用户必须根据自己 Mac 的架构挑选对应版本，对非技术用户存在理解门槛。

实践中两者互补：默认打包同时产出双架构的 dmg/zip（体积优先），而build:universal提供单一文件的兜底分发（体验优先）。从源码看，universal 分支在 ninja/build.sh 第 221-223 行与第 236-238 行被单独处理，与普通架构构建走不同命令路径。

安装阶段还有一处与分发强相关的现实问题：项目未配置开发者签名公证（gatekeeperAssess: false），首次运行可能提示"无法打开，因为无法验证开发者"。仓库自带的 docs/README.txt（会被自动打包进 DMG）给出了两种解锁方式：

# 方法一（推荐）：清除应用上的隔离属性标记 xattr -cr /Applications/Nigate.app # 方法二：禁用 Gatekeeper（需系统设置中开启"任何来源"） sudo spctl --master-disable

六、恢复 ARM64 配置与版本回退

如果需要恢复到之前的 ARM64 专属配置（例如只想维护 Apple Silicon 单一产物、减小发布体积），用备份文件覆盖当前配置即可：

cp package.json.backup.arm64 package.json cp ninja/build.sh.backup.arm64 ninja/build.sh

恢复后注意两点差异：其一，package.json.backup.arm64的版本号是 1.4.3，覆盖后产物名称与 About 页面显示的版本会随之回退（pnpm run sync-version会按 package.json 同步）；其二，备份版 build.sh 不识别--universal、--x64参数，且 Electron 镜像默认未启用（注释在第 146-148 行，需要手动取消注释）。

七、注意事项小结

• --universal产出的是单一 fat binary，一个文件同时支持 x64 与 arm64；["x64", "arm64"]则产出两个独立包。
• 通用二进制体积更大，但用户只需下载一个文件；双独立包体积更小，但需要用户自行判断 Mac 架构。
• Electron 下载镜像已默认开启（npmmirror）；切换官方源用ELECTRON_MIRROR=""显式置空。
• 默认打包会串行构建两个架构并预先清理挂载的 DMG，若构建中断，可先./ninja/build.sh --clean再重试。
• 本文所有命令与配置均以当前仓库实际内容为准，涉及的配置文件为 package.json、package.json.backup.arm64、ninja/build.sh、ninja/build.sh.backup.arm64、ninja/build-lang.sh 与 docs/README.txt，可自行对照研读。

• 桌面应用
• 存储