以下是完整的 Puppeteer 项目打包过程总结，学习记录：
📦 Puppeteer 项目打包完整流程
1. 项目结构准备
Web-TV/
├── black.html # 黑屏页面
├── player/
│ ├── PagePlayer.js # 播放器核心逻辑
│ └── config.json # 配置文件
├── chromium/ # Chromium 可执行文件（可选）
├── server.js # 主入口文件
└── package.json # 项目配置2. 关键配置修改
package.json 配置
{
"name": "Web-TV",
"version": "1.0.0",
"main": "server.js",
"bin": "server.js", // 必须添加的入口声明
"scripts": {
"start": "node server.js",
"build": "pkg . --targets node18-win-x64 --output Web-TV.exe"
},
"dependencies": {
"puppeteer": "^21.11.0" // 建议使用最新版
},
"pkg": {
"assets": [ // 必须包含所有静态资源
"black.html",
"player/config.json",
"chromium/**/*"
],
"scripts": [
"server.js",
"player/**/*.js" // 包含所有子目录JS文件
]
}
}3. 代码适配要点
文件路径处理（关键！）
// PagePlayer.js 中修改路径处理逻辑
const isPkg = typeof process.pkg !== 'undefined';
const blackPath = isPkg
? path.join(path.dirname(process.execPath), 'black.html')
: path.join(__dirname, '../black.html');HTTP 请求替代方案
// 替代 axios 的方案（三选一）
// 方案1：使用原生 http 模块
const http = require('http');
// 方案2：使用 node-fetch（需 npm install node-fetch@2）
const fetch = require('node-fetch');
// 方案3：嵌入式黑屏（无需外部文件）
await page.setContent(`<html><body style="background:black"></body></html>`);4. 打包执行命令
# 清理环境
rm -rf node_modules package-lock.json
# 安装依赖（建议使用淘宝镜像）
npm install --registry=https://registry.npmmirror.com
# 执行打包（生成 Windows 可执行文件）
pkg . --targets node18-win-x64 --output Web-TV.exe5. 常见问题解决
| 问题现象 | 解决方案 |
|---|---|
Cannot find module | 检查 pkg.assets 是否包含所有依赖文件 |
| 黑屏文件加载失败 | 使用嵌入式HTML或绝对路径处理 |
| 打包体积过大 | 添加 !node_modules/** 排除无用文件 |
| 杀毒软件拦截 | 将 chromium 目录加入白名单 |
6. 最佳实践建议
- 路径处理原则：
- 开发环境用
__dirname - 打包环境用
process.execPath获取可执行文件所在目录
- 资源加载方式：
// 通用资源加载方法
function getAssetPath(relativePath) {
return path.join(
typeof process.pkg !== 'undefined'
? path.dirname(process.execPath)
: process.cwd(),
relativePath
);
}- 调试技巧：
# 查看打包文件包含内容
strings Web-TV.exe | grep "black.html"
# 启用详细日志
pkg --debug .7. 学习要点记录
- pkg 工作原理：将项目打包成 V8 字节码快照，需显式声明资源文件
- 路径陷阱：打包后
__dirname指向C:\snapshot虚拟目录 - 依赖管理：生产依赖必须通过
npm install --save安装 - Chromium 处理：推荐使用
puppeteer-core+ 本地 Chromium
按照这个流程操作，即可生成可在无 Node.js 环境的 Windows 机器上直接运行的独立可执行文件。建议在实际操作时配合 --debug 参数逐步验证打包结果。
npx puppeteer browsers install chrome@latest
npm install -g json
json -f package.json
pkg . –targets node18-win-x64
可能使用到的命令
npm install -g json
json -f package.json
pkg . –targets node18-win-x64