使用pkg打包Node.js项目遇puppeteer依赖警告，操作后仍失败

架构老林

2026-8-23

解决pkg打包Node.js项目时Puppeteer本地Chromium的分发问题

常见操作误区及修正方案

目录结构错误
你可能直接把node_modules/puppeteer整个目录移到了可执行文件同级，但pkg要求的是把.local-chromium目录放到可执行文件同级的puppeteer文件夹内。正确的目录结构应该是：
```
你的项目可执行文件.exe
└── puppeteer/
    └── .local-chromium/
        └── 对应平台的Chromium版本文件夹（比如win64-123456）
```

未手动指定Chromium路径
Puppeteer默认会从node_modules查找Chromium，即使目录放对了也可能找不到。需要在代码里硬编码Chromium的路径：

const puppeteer = require('puppeteer');
const path = require('path');

// 拼接可执行文件同级的Chromium路径
const chromiumExePath = path.join(
  path.dirname(process.execPath),
  'puppeteer',
  '.local-chromium',
  'win64-123456', // 替换成你本地实际的版本文件夹名
  'chrome-win',
  'chrome.exe'
);

(async () => {
  const browser = await puppeteer.launch({
    executablePath: chromiumExePath,
    // 其他配置
  });
  // 业务代码
})();

package.json配置缺失
检查你的package.json是否配置了pkg的assets和ignore字段，确保pkg正确处理Puppeteer文件：
```
"pkg": {
  "assets": ["node_modules/puppeteer/**/*"],
  "ignore": ["node_modules/puppeteer/.local-chromium/**/*"]
}
```
这个配置是让pkg打包Puppeteer的核心代码，但忽略体积庞大的本地Chromium，之后你手动分发Chromium目录即可。
Chromium版本不匹配
确认你分发的.local-chromium里的Chromium版本，和项目依赖的Puppeteer要求的版本完全一致。可以打开node_modules/puppeteer/package.json，查看puppeteer.chromium_revision字段的版本号，避免因版本不一致导致启动失败。