调试NodeJS CLI工具时Sourcemaps无法正常工作

项目创建流程 #

1. 创建NX工作区：

npx -y create-nx-workspace
> cli-tools
> stack: none
> prettier: yes
> CI: later
> remote caching: no

cd cli-tools
code .

2. 安装依赖并生成库：

npm i -D @nx/node
npx nx generate @nx/js:library --name biss --directory packages/biss --publishable --importPath=@company/cli-tools --bundler tsc --linter eslint --unitTestRunner jest

3. 修改包的index.ts：

#!/usr/bin/env node

const cwd = process.cwd();
console.warn(`Current directory "${cwd}"`);

4. 更新package.json：

{
  "name": "@company/cli-tools",
  ...,
  "engines": {
    "node": ">=10.12.0"
  },
  "bin": {
    "biss": "dist/index.js"
  }
}

5. 构建包：

npx nx build --configuration=production --project biss

6. 安装Verdaccio并发布包：

npm i --global verdaccio
verdaccio
> http://localhost:4873/
npm adduser --registry http://localhost:4873/
> Username: example
> Password: example
> Email: example@example.com

cd packages/biss
npm publish --registry http://localhost:4873/

7. 全局安装工具：

npm install --global @company/cli-tools --registry http://localhost:4873/

调试遇到的问题 #

• 开启VSCode自动附加（Debug > Javascript: Auto Attach Filter设为always），添加断点后运行biss --inspect，VSCode尝试附加调试器但断点未命中。
• 添加debugger;语句可命中，但进入的是JS打包文件index.js而非TS源文件，TS文件中的断点始终未绑定。
• 修改tsconfig的sourceRoot字段并包含源文件后，sourcemap文件路径指向正确目录，但运行biss --inspect时VSCode仍不显示TS文件。
• 在工具安装目录添加launch.json配置，问题仍未解决。

解决方案 #

1. 确保构建生成正确的Sourcemap #

修改packages/biss/tsconfig.lib.json，配置如下：

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}

2. 调整NX生产构建配置 #

修改packages/biss/project.json的构建配置，确保生产模式下保留Sourcemap：

{
  "targets": {
    "build": {
      "options": {
        "sourceMap": true
      },
      "configurations": {
        "production": {
          "sourceMap": true
        }
      }
    }
  }
}

3. 发布时包含Sourcemap与源文件 #

更新packages/biss/package.json的files字段，确保包含必要文件：

{
  "files": [
    "dist",
    "src"
  ]
}

4. 本地调试替代全局安装调试 #

在项目根目录的.vscode/launch.json中添加调试配置，直接调试本地构建产物：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug CLI",
      "program": "${workspaceFolder}/packages/biss/dist/index.js",
      "args": [],
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/packages/biss/dist/**/*.js"]
    }
  ]
}

使用该配置启动调试，断点可直接命中TS源文件，无需发布到私有仓库。

5. 全局安装版本的路径映射配置 #

若必须调试全局安装的CLI，在VSCode的.vscode/settings.json中添加路径映射：

{
  "debug.javascript.sourceMapPathOverrides": {
    "webpack://@company/cli-tools/*": "${workspaceFolder}/packages/biss/src/*"
  }
}

该配置可让VSCode将Sourcemap中的路径关联到本地TS源文件。

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