发布NPM包时提示builtins is not a function报错求助

安全阿岳

2026-8-26

问题描述

执行npm包发布操作时终端返回错误：
npm ERR! builtins is not a function

完整错误调用栈：

37 verbose stack TypeError: builtins is not a function
37 verbose stack     at validate (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/node_modules/validate-npm-package-name/lib/index.js:55:3)
37 verbose stack     at Result.setName (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/node_modules/npm-package-arg/lib/npa.js:127:17)
37 verbose stack     at new Result (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/node_modules/npm-package-arg/lib/npa.js:119:10)
37 verbose stack     at Function.resolve (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/node_modules/npm-package-arg/lib/npa.js:56:15)
37 verbose stack     at npa (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/node_modules/npm-package-arg/lib/npa.js:26:18)
37 verbose stack     at Function.pickRegistry (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/node_modules/npm-registry-fetch/lib/index.js:189:10)
37 verbose stack     at Publish.exec (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/lib/commands/publish.js:107:33)
37 verbose stack     at async module.exports (/home/runner/work/typeorm-seeding/typeorm-seeding/node_modules/npm/lib/cli.js:66:5)

根因定位

错误触发点在validate-npm-package-name包的包名校验逻辑，属于典型的嵌套依赖版本不兼容问题：

1.x版本的builtins包默认导出函数，符合validate-npm-package-name@<5.0.0的调用规范
2.x及以上版本的builtins修改了导出规则，不再支持直接以函数形式调用，一旦依赖树中该包版本被错误提升、锁文件失效拉取了不匹配的高版本，就会抛出builtins is not a function的类型错误
从报错路径判断，当前是项目本地node_modules中嵌套的npm依赖出现版本漂移，常见于CI环境依赖缓存失效、本地node_modules损坏、npm全局安装损坏的场景。

解决步骤

按优先级依次尝试：

清理依赖后重装
删除项目下的node_modules目录和对应包管理器的锁文件，重新安装依赖后重试发布：
```
rm -rf node_modules package-lock.json
npm install
```
CI环境下建议先清空旧的依赖缓存，再执行安装步骤，避免缓存拉取到错误版本的依赖包。
修复全局npm安装
如果全局npm本身的依赖树损坏，也会触发同类错误，重装固定版本的npm即可：
```
# 可根据项目需求替换为对应大版本，比如npm@8、npm@9
npm install -g npm@10
```
CI流水线中建议显式声明安装固定版本的npm，避免使用环境默认的预安装版本出现兼容问题。
强制对齐依赖版本
若依赖提升规则导致版本漂移，npm 8.3.0及以上版本可在package.json中添加overrides配置，强制嵌套依赖使用兼容版本：
```
{
  "overrides": {
    "validate-npm-package-name": "^5.0.0"
  }
}
```
配置保存后重新执行依赖安装，再运行发布命令。
临时应急修复
若需要快速在当前环境绕过问题，可手动进入报错的包目录安装兼容版本的builtins：
```
cd node_modules/npm/node_modules/npm-registry-fetch/node_modules/validate-npm-package-name
npm install builtins@1.0.3
```
该方案仅对当前环境生效，重新安装依赖后会失效，不建议作为长期方案使用。

内容的提问来源于stack exchange，提问作者Jorge Bodega Fernanz