为什么每次 pkg 打包都要重新下载 100MB？PKG_CACHE_PATH 打包缓存完整指南

为什么每次 pkg 打包都要重新下载 100MB？PKG_CACHE_PATH 打包缓存完整指南

【免费下载链接】pkgPackage your Node.js project into an executable项目地址: https://gitcode.com/gh_mirrors/pk/pkg

用 pkg 把 Node.js 项目打包成可执行文件时，第一次跑可能就要等上几分钟；更烦人的是，第二次打包它还在重新下载那 50-100MB 的 Node.js 基础二进制。问题几乎都出在同一个地方：打包缓存没有落到固定位置，pkg 每次都把"下载基座"当成必经流程。下文的排查、配置和 CI 复用方案都围绕一个变量展开：PKG_CACHE_PATH，它决定缓存目录放在哪，默认值是~/.pkg-cache，可以指向任意路径。

慢打包排查：时间到底花在哪了

先复现问题。对一个中等规模的入口文件执行：

pkg -d app.js

-d打开调试输出后，留意这一行：

> Fetching base Node.js binaries to PKG_CACHE_PATH

看到这行，基本就能下结论了：这一轮打包里，pkg 去远程拉取了对应 Node.js 版本和平台的基础二进制。这类文件按"版本 + 平台 + 架构"区分，单个普遍在 50-100MB；如果你一次指定多个 target（比如同时出 linux-x64 和 win-x64），就是好几倍。这一步走完之后，剩下的文件收集、snapshot 写入才是打包本体。

换句话说，慢不是慢在"打包"，而是慢在"每次都要先备料"。备料只该做一次，做完就该留在本地——这正是下面要配置的东西。

让缓存有固定家：PKG_CACHE_PATH 的三种配置方式

结论先行：把PKG_CACHE_PATH指到一个你确定还在、磁盘够大的路径，下载只做一次。变量不设置时，缓存默认落在~/.pkg-cache，见 README.md 的环境变量表。三种设置方式，按"生效范围"选：

# 方式一：当前终端会话内生效 export PKG_CACHE_PATH=/data/shared/pkg-cache pkg app.js # 方式二：只对本次命令生效，最省事 PKG_CACHE_PATH=/data/shared/pkg-cache pkg app.js # 方式三：写入 shell 配置，长期生效 echo 'export PKG_CACHE_PATH=/data/shared/pkg-cache' >> ~/.bashrc # zsh 用户改为 ~/.zshrc source ~/.bashrc

怎么选很简单：

• 只是自己偶尔打包 → 默认~/.pkg-cache就够了，不一定要改
• 家里 / 开发机上磁盘分区有讲究（比如/很小、数据盘很大）→ 用方式一或方式三把缓存挪过去
• 临时验证一次 → 方式二，命令前内联指定，不污染 shell 环境

配置本身没有魔法，收益来自两点：缓存文件按 target 归档，同一个 target 第二次直接命中；而且缓存目录是全局的，不绑定某个项目，换个项目打包也照样能用。

多项目共用一份缓存：团队共享目录做法

如果你们组有几个人、几个仓库都在用 pkg，各自散落的~/.pkg-cache意味着每个人、每个仓库都在重复下载同样的二进制。把大家的缓存指到同一块共享盘：

# 例如内网共享盘 / 团队约定目录 export PKG_CACHE_PATH=/data/shared/pkg-cache

做法上注意两点：

1. 共享目录要有读写权限，且容量按"Node 版本数 × 平台架构数 × 100MB"粗估留足空间，常见组合撑死几个 GB。
2. 缓存是按 Node 版本和平台架构分子目录存的，不同项目、不同版本之间不会互相覆盖，所以共享是安全的；谁先下载，其他人后到命中。

对 CI 场景，这个思路还会再进一步：不但团队共享，还要跨流水线复用。

CI 流水线里复用缓存：别每次提交都重新下载

CI runner 的临时工作区每次构建都是干净的，~/.pkg-cache默认值在这里等于"没有缓存"。解法是把缓存目录纳入 CI 平台自带的缓存机制，以 GitHub Actions 为例：

- name: Reuse pkg base binary cache uses: actions/cache@v3 with: path: ${{ env.PKG_CACHE_PATH }} key: ${{ runner.os }}-pkg-${{ hashFiles('package.json') }}

key 的拼法是"操作系统 + package.json 内容哈希"：

• 不同系统（ubuntu / macos / windows runner）下载的基座二进制完全不同，必须拆开，否则缓存串味
• package.json一变（通常是升级 Node 引擎版本），缓存 key 变化、自动触发一次重新下载；没变就直接 restore，跳过整个 fetch 阶段

一条流水线省 50-100MB 下载不多，但一天跑几十次构建、多仓库并行时，这部分网络等待就是实打实的排队时间。

验证缓存是否命中：先看日志，再看目录

判断方法分两层，日志优先。

第一次打包（缓存为空）时，调试输出里会出现 lib/index.ts 中这行：

> Fetching base Node.js binaries to PKG_CACHE_PATH

第二次打包同一个 target，如果这行不再出现、打包直接进入 snapshot 写入阶段，就说明命中了本地缓存。再用磁盘占用交叉确认：

du -sh "$PKG_CACHE_PATH" ls "$PKG_CACHE_PATH"

目录体积稳定、没有新增下载文件，缓存链路就是通的。反过来，如果第二次仍看到 Fetching 日志，多半是环境变量没传到执行 pkg 的那个进程里，跳去下一节排查。

缓存三个常见坑的排查

坑一：目录没有写权限。

报Permission denied时，先确认$PKG_CACHE_PATH指向的目录当前用户可写，必要时把父目录权限修正为 755 并保证属主正确：

chmod -R 755 "$PKG_CACHE_PATH"

共享盘上尤其注意：缓存目录如果建在某个人的私有子目录里，其他人的 pkg 进程读不进去，共享就名存实亡了。

坑二：缓存文件损坏。

下载被网络中断掐断，可能留下半个文件，后续打包时校验不过或直接失败。处理方式粗暴但有效——删掉整个缓存目录重跑，pkg 会重新拉取完整基座：

rm -rf "$PKG_CACHE_PATH" pkg app.js

坑三：环境变量"设了但没生效"。

典型症状是日志里缓存路径还是~/.pkg-cache。在同一个终端里验证：

echo $PKG_CACHE_PATH

为空说明export没执行成功，或你是在另一个终端、另一个 CI step 里跑 pkg 的。内联写法（PKG_CACHE_PATH=... pkg app.js）只在单条命令内有效，写进~/.bashrc后要source或重开终端才生效——这是最常见的误判来源。

别让缓存目录无限膨胀：定期清理

缓存只进不出，半年后里面会沉淀你早已不用的 Node 14、Node 16 旧基座。一条清理命令保留最近 30 天动过的目录：

find "$PKG_CACHE_PATH" -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;

两个补充：

• 清理前先du -sh看一眼总占用，心里有数再删。
• 共享目录里如果混着别的版本标记文件夹，可以配合PKG_IGNORE_TAG环境变量（见 README.md 环境变量表）让 pkg 忽略匹配 pkg-fetch 版本号的额外目录，避免误伤。

收尾：一句话记住这套机制

PKG_CACHE_PATH只回答一个问题：Node.js 基础二进制的缓存放哪。本地指到数据盘，团队指到共享盘，CI 里挂上actions/cache，下载就只会发生一次。打包命令本身不用改，lib/bin.ts 入口的参数也一个没动——省下来的全是网络等待时间。

【免费下载链接】pkgPackage your Node.js project into an executable项目地址: https://gitcode.com/gh_mirrors/pk/pkg