在使用pkg将 Node.js 项目打包成可执行文件时，经常会遇到下面这些问题：
- ❌ 打包过程中卡在Downloading Node.js binary
- ❌ 国内网络访问 GitHub / npm 镜像慢或失败
- ❌ pkg-fetch 自动下载失败，导致无法打包
其实pkg 支持手动下载并放入缓存目录，本文将详细介绍Windows 和 macOS 下 pkg 的手动依赖解决方案。
一、pkg 打包原理简述
pkg 在打包时，会自动下载对应版本的Node.js 运行时二进制文件，并缓存到本地目录：
Windows：
C:\Users\<用户名>\.pkg-cachemacOS / Linux：
~/.pkg-cache
缓存文件命名格式示例：
fetched-v16.16.0-win-x64 fetched-v16.16.0-macos-x64 fetched-v16.16.0-linux-x64只要缓存存在，pkg 不会再联网下载。
二、pkg-fetch 官方下载地址
pkg 使用的 Node 二进制由pkg-fetch提供，官方 Release 地址：
https://github.com/vercel/pkg-fetch/releases⚠️ 国内访问较慢，建议使用代理或提前下载
三、Windows：pkg 手动放置缓存（Win x64）
1️⃣ pkg 缓存目录
C:\Users\Administrator\.pkg-cachepkg 当前常用缓存版本目录：
C:\Users\Administrator\.pkg-cache\v3.42️⃣ 查看已有缓存
PSC:\Users\Administrator\.pkg-cache\v3.4>ls示例输出：
目录: C:\Users\Administrator\.pkg-cache\v3.4 Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 2023/8/27 15:15 34778624 fetched-v16.16.0-win-x64说明：
v3.4：pkg-fetch 版本fetched-v16.16.0-win-x64：Node v16.16.0 的 Windows 64 位运行时
3️⃣ 手动下载 Node 二进制
从 pkg-fetch Release 中下载对应文件，例如：
node-v16.16.0-win-x64重命名为：
fetched-v16.16.0-win-x64然后放入目录：
C:\Users\Administrator\.pkg-cache\v3.4\4️⃣ Git for Windows 离线包（补充）
如果 pkg 构建过程中依赖 Git，可手动下载 Git 安装包：
https://cdn.npmmirror.com/binaries/git-for-windows/v2.24.0.6.windows.1/Git-2.24.0.6-64-bit.exe避免构建脚本中 Git 下载失败。
四、macOS：pkg 手动缓存配置
1️⃣ pkg 缓存目录
cd/Users/用户名/.pkg-cache/v3.42️⃣ 查看缓存内容
tree示例输出：
. ├── fetched-v14.20.0-macos-x64.downloading ├── fetched-v16.16.0-linux-x64 ├── fetched-v16.16.0-macos-x64 ├── fetched-v16.16.0-macos-x64-signed ├── fetched-v16.16.0-win-x64 ├── fetched-v18.5.0-macos-x64 └── fetched-v18.5.0-macos-x64-signed 1 directory, 7 files说明：
| 文件名 | 说明 |
|---|---|
macos-x64 | macOS Intel |
linux-x64 | Linux |
win-x64 | Windows |
*-signed | Apple 官方签名版本 |
.downloading | 未完成下载（可删除） |
3️⃣ 手动放置 macOS Node 二进制
下载对应版本后：
mvnode-v18.5.0-macos-x64 fetched-v18.5.0-macos-x64放入：
~/.pkg-cache/v3.4/如果存在.downloading文件，可直接删除。
五、指定 Node 版本打包（强烈推荐）
在 pkg 打包时显式指定 Node 版本，避免自动下载其他版本：
pkg index.js --targets node16-win-x64 pkg index.js --targets node16-macos-x64 pkg index.js --targets node18-linux-x64这样 pkg 只会查找对应缓存文件。
六、常见问题排查
❓ pkg 仍然尝试下载？
- 检查文件名是否完全一致
- 是否放在正确的
v3.4目录 - Node 版本是否和
--targets匹配
❓ 如何查看 pkg-fetch 版本？
pkg --debug或查看缓存目录名（如v3.4）
七、总结
✅ pkg 支持完全离线打包
✅ 手动缓存可解决 99% 网络问题
✅ 推荐提前下载并统一管理.pkg-cache
适合：
- 内网环境
- CI / Docker 构建
- 国内网络不稳定环境
