Nx项目如何构建无需依赖node_modules的独立可执行脚本

AI 小北

2026-8-27

问题原因

Nx 对 Node 后端项目的默认 Webpack 打包规则，会自动将 node_modules 下的所有第三方依赖标记为 external（外部依赖），不会打包进最终的 main.js 产物，运行时需要从本地 node_modules 目录加载对应模块。你删除 node_modules 后出现的 Cannot find module 'tslib' 报错，就是因为 tslib 作为Nx/TypeScript项目的基础依赖，默认被排除在打包产物外导致的。

配置步骤

按以下修改配置即可生成完全自包含、仅需Node运行环境即可启动的单文件产物：

找到后端项目的 Webpack 配置文件，路径通常为 apps/backend/webpack.config.js。如果文件不存在则手动创建，后续需要在构建配置中关联该文件。
写入以下配置覆盖默认的外部依赖规则：

const { composePlugins, withNx } = require('@nx/webpack');

module.exports = composePlugins(withNx(), (config) => {
  // 清空默认的外部依赖列表，所有node_modules依赖默认打入bundle
  config.externals = [];
  // 仅将Node.js原生内置模块（如fs、path、http等）保留为外部依赖，这类模块由Node运行时直接提供，无需打包
  config.externalsPresets = {
    node: true
  };
  // 强制生产模式压缩，进一步减小产物体积
  config.mode = 'production';
  return config;
});

打开后端项目的 project.json 文件，找到 build 目标节点，补充/修改以下配置项：

{
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        // 保留你原有其他配置不变，仅补充以下两项
        "webpackConfig": "apps/backend/webpack.config.js",
        "externalDependencies": "none"
      }
    }
  }
}

特殊依赖处理：如果项目中用到了C++编写的原生Node模块（比如bcrypt、sqlite3等），这类模块无法被打包进JS文件，只需要把它们单独加入外部依赖列表即可，这类依赖数量极少，不会造成产物体积暴涨：

// 在webpack配置的config.externals数组中加入原生模块名即可
config.externals = ['bcrypt', 'sqlite3'];

验证与部署

执行构建命令 nx build backend，产物默认输出到 dist/apps/backend 目录
将输出的dist目录单独复制到一个没有node_modules的空白目录，执行node main.js，如果服务能正常启动，说明自包含打包配置生效
部署到Heroku时仅需要上传dist目录的内容，不需要上传项目根目录的全量node_modules，产物体积通常仅几MB到十几MB，完全符合Heroku的Slug大小限制。

如果追求更快的构建速度，可以将构建executor替换为Nx内置的@nx/esbuild:esbuild，只需要在build配置中设置"bundle": true、"external": []，即可实现相同的单文件打包效果，构建速度比Webpack快5-10倍。

内容的提问来源于stack exchange，提问作者Adam A