Node.js跨平台打包神器：pkg完整使用指南

Node.js跨平台打包神器：pkg完整使用指南

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

pkg是一个强大的Node.js应用程序打包工具，能够将你的Node.js项目打包成单个可执行文件，无需在目标设备上安装Node.js环境。这个工具对于商业应用分发、演示版本制作和跨平台部署来说是一个终极解决方案。

📦 什么是pkg及其核心功能

pkg允许你将Node.js应用程序及其所有依赖项打包成一个独立的可执行文件。这意味着你可以：

• 创建不需要源代码的商业版本应用
• 制作演示或试用版本
• 支持跨平台编译（一次打包，多平台运行）
• 部署时无需安装Node.js和npm
• 将资源文件嵌入到可执行文件中增强便携性

🚀 快速安装与基础使用

安装pkg非常简单，只需要运行：

npm install -g pkg

安装完成后，基本的打包命令格式为：

pkg [options] <input>

其中<input>可以是入口文件路径、package.json文件路径或项目目录路径。

🎯 目标平台配置

pkg支持为多个目标平台生成可执行文件，目标格式为：node版本-平台-架构

示例目标：

• node18-macos-x64 - macOS 64位
• node16-linux-arm64 - Linux ARM64
• node14-win-x64 - Windows 64位

你可以一次性为多个平台打包：

pkg -t node16-linux,node18-linux,node16-win index.js

⚙️ 配置文件设置

在package.json中配置pkg选项：

{
  "pkg": {
    "scripts": "build/**/*.js",
    "assets": "views/**/*",
    "targets": ["node14-linux-arm64"],
    "outputPath": "dist"
  }
}

• scripts: 需要编译的JavaScript文件
• assets: 需要作为原始内容打包的资源文件
• targets: 目标平台列表
• outputPath: 输出目录

🔧 高级功能特性

压缩优化

使用压缩算法减小可执行文件大小：

pkg --compress Brotli index.js
pkg --compress GZip index.js

运行时选项

将Node.js运行时选项嵌入到可执行文件中：

pkg --options "max-old-space-size=1024,expose-gc" index.js

调试模式

查看详细的打包过程：

pkg --debug index.js

📁 文件系统处理

打包后的应用程序使用快照文件系统，所有文件都嵌入到可执行文件中：

• __filename 变为 /snapshot/path/app.js
• __dirname 变为 /snapshot/path
• 使用 path.join(__dirname, '../assets') 访问打包的资源

🛠️ 原生模块支持

pkg支持原生模块（.node文件），但需要注意：

• 原生模块需要针对目标Node.js版本编译
• 在配置文件中明确指定.nod文件作为资源
• 完全静态的Node二进制文件无法加载原生绑定

🌐 环境变量配置

pkg支持以下环境变量：

• PKG_CACHE_PATH: 自定义node二进制文件缓存路径
• PKG_IGNORE_TAG: 忽略pkg-fetch版本创建的额外文件夹
• MAKE_JOB_COUNT: 配置编译使用的进程数

🔍 故障排除指南

常见错误解决

ENOENT: no such file or directory, uv_chdir

• 原因：运行应用程序时删除了所在目录
• 解决：确保不删除process.cwd()目录

ERR_INSPECTOR_NOT_AVAILABLE

• 原因：使用了NODE_OPTIONS调试选项
• 解决：生产环境禁用调试选项

require(...).internalModuleStat is not a function

• 原因：NODE_OPTIONS环境变量冲突
• 解决：检查并清理NODE_OPTIONS设置

💡 最佳实践建议

1. 版本匹配: 确保打包目标Node版本与系统Node版本一致
2. 资源管理: 使用path.join(__dirname, 'path/to/asset')访问资源
3. 配置优化: 在package.json中配置pkg选项简化命令行参数
4. 测试验证: 在各个目标平台上测试打包后的可执行文件
5. 安全考虑: 生产环境避免使用--debug标志

pkg为Node.js开发者提供了一个简单而强大的解决方案，让你的应用程序部署变得更加便捷和高效。无论是商业应用分发还是跨平台部署，pkg都能帮助你轻松应对各种场景需求。

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