pkg 构建缓存位置：PKG_CACHE_PATH 自定义与清理

pkg 构建缓存位置：PKG_CACHE_PATH 自定义与清理

【免费下载链接】pkg 项目地址: https://gitcode.com/gh_mirrors/pkg/pkg

在使用 pkg 打包 Node.js 应用时，频繁的构建会产生大量缓存文件，默认存储在用户目录下的 .pkg-cache 文件夹中。随着项目迭代，这些缓存可能占用过多磁盘空间，或因权限问题导致构建失败。本文将详细介绍如何通过 PKG_CACHE_PATH 环境变量自定义缓存路径，以及安全清理缓存的方法，帮助开发者优化构建流程。

缓存路径的默认行为

pkg 在构建过程中会下载预编译的 Node.js 基础二进制文件（base binaries），并存储在默认缓存目录中。根据 环境变量说明，默认路径为：

• Linux/macOS：~/.pkg-cache
• Windows：C:\Users\<用户名>\.pkg-cache

这些缓存文件会根据 pkg-fetch 版本自动创建子目录（如 v3.4），结构示例如下：

~/.pkg-cache/
├── v3.4
│   ├── node-v18.18.0-linux-x64
│   └── node-v18.18.0-macos-arm64
└── v3.5
    └── node-v20.9.0-win-x64

自定义缓存路径（PKG_CACHE_PATH）

临时生效方式

在执行 pkg 命令前通过环境变量指定路径，仅对当前终端会话生效：

PKG_CACHE_PATH=/data/pkg-cache pkg index.js

永久生效配置

Linux/macOS 系统

编辑 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）：

echo 'export PKG_CACHE_PATH="/data/pkg-cache"' >> ~/.bashrc
source ~/.bashrc

Windows 系统

通过系统属性设置环境变量：

1. 打开 控制面板 > 系统 > 高级系统设置
2. 点击 环境变量，在用户变量中新建：
   • 变量名：PKG_CACHE_PATH
   • 变量值：D:\pkg-cache

配置验证

设置完成后，可通过以下命令验证：

echo $PKG_CACHE_PATH  # Linux/macOS
echo %PKG_CACHE_PATH%  # Windows

输出应显示自定义路径，如 /data/pkg-cache。

缓存清理策略

手动清理

直接删除缓存目录下的文件：

# 清理默认缓存
rm -rf ~/.pkg-cache/*

# 清理自定义缓存
rm -rf $PKG_CACHE_PATH/*

按版本清理

若需保留特定版本缓存，可删除指定版本目录：

# 删除 v3.4 版本缓存
rm -rf $PKG_CACHE_PATH/v3.4

自动化清理脚本

创建清理脚本 clean-pkg-cache.sh 并添加执行权限：

#!/bin/bash
CACHE_DIR="${PKG_CACHE_PATH:-$HOME/.pkg-cache}"
echo "Cleaning pkg cache in $CACHE_DIR..."
rm -rf "$CACHE_DIR"/*
echo "Cache cleaned successfully"

使用方法：chmod +x clean-pkg-cache.sh && ./clean-pkg-cache.sh

缓存路径相关源码解析

pkg 的缓存路径处理逻辑位于 lib/fabricator.ts，核心代码片段如下：

// 从环境变量获取缓存路径，默认 ~/.pkg-cache
const cachePath = process.env.PKG_CACHE_PATH || path.join(os.homedir(), '.pkg-cache');

缓存下载逻辑在 lib/producer.ts 中实现，通过 fetchBaseBinary 函数处理基础二进制文件的下载与缓存：

async function fetchBaseBinary(target: Target) {
  const cacheDir = getCacheDir(target);
  // 检查缓存是否存在，不存在则下载
  if (!fs.existsSync(cacheDir)) {
    await downloadBinary(target, cacheDir);
  }
  return cacheDir;
}

常见问题解决

权限不足错误

症状：EACCES: permission denied 错误
解决：将缓存路径修改为非系统目录，如 /data/pkg-cache，并确保有读写权限：

mkdir -p /data/pkg-cache && chmod 755 /data/pkg-cache

缓存文件损坏

症状：构建时报错 invalid checksum for cached binary
解决：清理对应版本缓存后重新构建：

rm -rf $PKG_CACHE_PATH/v3.4/node-v18.18.0-linux-x64

跨平台缓存共享

场景：在多系统环境中共享缓存
解决：将缓存路径设置为共享目录（如 NFS 挂载路径），但需注意不同平台的二进制文件不兼容。

最佳实践总结

1. 设置自定义缓存路径：避免系统盘空间占用，建议设置到非系统分区
2. 定期清理：结合 CI/CD 流程，在每次构建前执行缓存清理
3. 版本管理：对于稳定项目，可保留当前使用版本的缓存，删除旧版本
4. 权限控制：确保缓存目录权限为 755，避免因权限问题导致构建失败

通过合理配置 PKG_CACHE_PATH 和实施有效的缓存管理策略，可以显著提升 pkg 构建效率，减少磁盘空间占用，避免因缓存问题导致的构建失败。更多细节可参考 pkg 官方文档 README.md 和环境变量配置说明 lib/common.ts。

【免费下载链接】pkg 项目地址: https://gitcode.com/gh_mirrors/pkg/pkg