为何在package.json外运行esbuild脚本会出现路径解析错误？

问题场景 #

在package.json的scripts中使用esbuild压缩CSS可正常运行，配置如下：

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "build": "esbuild foo/src/css/public.css --minify=true --sourcemap --outfile=foo/css/public.css"
},

但将逻辑移至外部JS文件后，出现路径解析错误，外部脚本代码：

require('esbuild').buildSync({
    entryPoints: ['foo/src/css/public.css'],
    outfile: 'foo/css/public.css',
    minify: true,
    bundle: false,
    sourcemap: true,
});

错误信息：

errors: [
  {
    detail: undefined,
    id: '',
    location: null,
    notes: [],
    pluginName: '',
    text: 'Could not resolve "foo/src/css/public.css"'
  }
]

解决方法 #

核心原因是Node脚本中相对路径的解析基准与npm scripts不同：npm scripts默认以项目根目录为工作目录，而直接运行Node脚本时，相对路径是相对于脚本文件所在目录或当前终端工作目录，导致路径不匹配。

方法1：使用绝对路径（推荐） #

借助Node的path模块，基于项目根目录生成绝对路径，确保无论脚本在哪运行，路径都正确：

const path = require('path');

require('esbuild').buildSync({
    entryPoints: [path.resolve(process.cwd(), 'foo/src/css/public.css')],
    outfile: path.resolve(process.cwd(), 'foo/css/public.css'),
    minify: true,
    bundle: false,
    sourcemap: true,
});

process.cwd()返回当前终端执行脚本时的工作目录，和npm scripts的工作目录保持一致，完全匹配原来的路径逻辑。

方法2：通过npm脚本调用外部文件 #

在package.json中新增脚本，通过npm执行外部文件，此时工作目录自动以项目根目录为准，无需修改路径：

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "build": "esbuild foo/src/css/public.css --minify=true --sourcemap --outfile=foo/css/public.css",
  "build:script": "node ./scripts/build.js" // 替换为你的外部脚本实际路径
}

执行时运行npm run build:script即可，路径逻辑和原build脚本完全一致。

方法3：调整相对路径（不推荐） #

如果外部脚本在项目子目录中（比如scripts/build.js），可手动调整相对路径指向项目根目录的目标文件：

require('esbuild').buildSync({
    entryPoints: ['../foo/src/css/public.css'], // 相对于脚本文件的路径
    outfile: '../foo/css/public.css',
    minify: true,
    bundle: false,
    sourcemap: true,
});

这种方式依赖脚本的固定位置，一旦脚本移动就需要修改路径，灵活性较差。

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