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 缓存目录

powershell 复制代码

C:\Users\Administrator\.pkg-cache

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

powershell 复制代码

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

2️⃣ 查看已有缓存

powershell 复制代码

PS C:\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 缓存目录

bash 复制代码

cd /Users/用户名/.pkg-cache/v3.4

2️⃣ 查看缓存内容

bash 复制代码

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 二进制

下载对应版本后：

bash 复制代码

mv node-v18.5.0-macos-x64 fetched-v18.5.0-macos-x64

放入：

bash 复制代码

~/.pkg-cache/v3.4/

如果存在 .downloading 文件，可直接删除。

五、指定 Node 版本打包（强烈推荐）

在 pkg 打包时显式指定 Node 版本，避免自动下载其他版本：

bash 复制代码

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 版本？

bash 复制代码

pkg --debug

或查看缓存目录名（如 v3.4）

七、总结

✅ pkg 支持完全离线打包

✅ 手动缓存可解决 99% 网络问题

✅ 推荐提前下载并统一管理 .pkg-cache

适合：

内网环境
CI / Docker 构建
国内网络不稳定环境