pkg 手动下载依赖并解决打包时网络下载失败（Win / macOS）

在使用pkg将 Node.js 项目打包成可执行文件时，经常会遇到下面这些问题：

• ❌ 打包过程中卡在Downloading Node.js binary
• ❌ 国内网络访问 GitHub / npm 镜像慢或失败
• ❌ pkg-fetch 自动下载失败，导致无法打包

其实pkg 支持手动下载并放入缓存目录，本文将详细介绍Windows 和 macOS 下 pkg 的手动依赖解决方案。

一、pkg 打包原理简述

pkg 在打包时，会自动下载对应版本的Node.js 运行时二进制文件，并缓存到本地目录：

• Windows：

  C:\Users\<用户名>\.pkg-cache

• macOS / 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-cache

pkg 当前常用缓存版本目录：

C:\Users\Administrator\.pkg-cache\v3.4

2️⃣ 查看已有缓存

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.4

2️⃣ 查看缓存内容

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

说明：

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 构建
• 国内网络不稳定环境