pkg打包NodeJS项目出现Cannot include file警告如何解决

pkg静态扫描依赖时只能识别JS/TS模块的引用关系，node-notifier、open这类依赖是运行时按当前平台动态拼接路径调用外部二进制，扫描阶段无法识别到这些非JS资源，就会抛出无法嵌入文件的警告，有两种成熟方案可以解决：

方案1：配置pkg资源声明实现单文件分发（推荐） #

这个方案不需要额外分发附属文件，所有资源都会被打进可执行包，用户拿到单个文件就能运行。

• 打开项目根目录的package.json，添加pkg配置段，声明所有需要打包的静态资源和目标构建平台：

{
  "pkg": {
    "assets": [
      "node_modules/node-notifier/vendor/**/*",
      "node_modules/open/xdg-open"
    ],
    "targets": [
      "node16-linux-x64",
      "node16-macos-x64",
      "node16-win-x64"
    ]
  }
}

• 在入口文件index.js的最顶部添加路径适配逻辑，让依赖在pkg的虚拟文件系统环境下能正确找到内嵌的二进制文件：

const path = require('path');
if (process.pkg) {
  // 固定资源查找根路径，指向pkg内嵌的node_modules目录
  const vendorBase = path.join(__dirname, 'node_modules/node-notifier/vendor');
  // 将xdg-open所在目录加入环境变量，方便open包查找
  process.env.PATH = `${path.join(__dirname, 'node_modules/open')}:${process.env.PATH}`;
}

• 如果使用的node-notifier版本没有自动适配pkg路径，直接在初始化通知实例时手动指定二进制路径即可，避免运行时找不着文件：

const notifier = require('node-notifier');
let notifyClient;

if (process.pkg) {
  const vendorBase = path.join(__dirname, 'node_modules/node-notifier/vendor');
  switch (process.platform) {
    case 'win32':
      notifyClient = new notifier.WindowsToaster({
        customPath: path.join(vendorBase, process.arch === 'x64' ? 'snoreToast/snoretoast-x64.exe' : 'snoreToast/snoretoast-x86.exe')
      });
      break;
    case 'darwin':
      notifyClient = new notifier.NotificationCenter({
        customPath: path.join(vendorBase, 'terminal-notifier.app/Contents/MacOS/terminal-notifier')
      });
      break;
    case 'linux':
      notifyClient = new notifier.NotifySend();
      break;
    default:
      notifyClient = notifier;
  }
} else {
  notifyClient = notifier;
}

// 后续发通知统一调用notifyClient.notify()即可

配置完成后重新执行pkg index.js，就不会再出现资源缺失的警告，生成的可执行文件可以直接单文件分发。

方案2：构建后自动拷贝依赖资源（无代码侵入） #

如果不想修改业务代码，可以在打包完成后通过脚本自动把需要的二进制文件按要求的目录结构拷贝到可执行文件同级目录，不用手动整理。

• 先安装文件操作依赖：npm install -D fs-extra
• 在项目根目录新建build.js脚本，写入如下逻辑：

const fse = require('fs-extra');
const path = require('path');

// 三个平台的构建配置
const platforms = [
  { key: 'linux', binName: 'index-linux', ext: '' },
  { key: 'macos', binName: 'index-macos', ext: '' },
  { key: 'win', binName: 'index-win.exe', ext: '.exe' }
];

// 需要拷贝的资源映射关系
const resources = [
  { src: 'node_modules/node-notifier/vendor/notifu/notifu.exe', dest: 'notifier/notifu.exe', platforms: ['win'] },
  { src: 'node_modules/node-notifier/vendor/notifu/notifu64.exe', dest: 'notifier/notifu64.exe', platforms: ['win'] },
  { src: 'node_modules/node-notifier/vendor/terminal-notifier.app/Contents/MacOS/terminal-notifier', dest: 'notifier/terminal-notifier', platforms: ['macos'] },
  { src: 'node_modules/node-notifier/vendor/snoreToast/snoretoast-x64.exe', dest: 'notifier/snoretoast-x64.exe', platforms: ['win'] },
  { src: 'node_modules/node-notifier/vendor/snoreToast/snoretoast-x86.exe', dest: 'notifier/snoretoast-x86.exe', platforms: ['win'] },
  { src: 'node_modules/open/xdg-open', dest: 'xdg-open', platforms: ['linux'] }
];

// 遍历处理每个平台的构建产物
platforms.forEach(plat => {
  const distPath = path.join(__dirname, 'dist', plat.key);
  fse.ensureDirSync(distPath);
  // 移动可执行文件到分发目录并重命名
  fse.moveSync(
    path.join(__dirname, plat.binName),
    path.join(distPath, `upworkNotifier${plat.ext}`),
    { overwrite: true }
  );
  // 拷贝当前平台需要的资源
  resources.filter(r => r.platforms.includes(plat.key)).forEach(res => {
    fse.copySync(path.join(__dirname, res.src), path.join(distPath, res.dest));
  });
});

• 修改package.json里的构建命令："build": "pkg index.js && node build.js"，后续执行npm run build，会自动在dist目录下生成三个平台的分发包，每个包内已经包含了对应平台需要的所有依赖文件，直接压缩分发即可。

分发注意事项 #

• MacOS平台分发时需要给主程序和terminal-notifier添加可执行权限，用户首次运行前执行chmod +x upworkNotifier notifier/terminal-notifier即可，否则会触发系统权限拦截
• Linux平台建议加个桌面环境检测逻辑，如果运行环境无图形桌面，自动降级为控制台日志或者其他通知渠道，避免调用通知组件报错
• Windows平台如果要减少系统SmartScreen拦截提示，可以给生成的exe文件添加代码签名

内容的提问来源于stack exchange，提问作者Ahmed Mohsen