macOS下NPM全局CLI工具scaffold命令无法运行求助

我在macOS上开发一款CLI工具，本地使用node index.js <command>命令能正常运行，但发布为npm包并全局安装后，package.json的bin字段中定义的scaffold命令无法正常工作。

我的package.json中bin字段配置如下：

"bin": {
    "scaffold": "index.js"
  },

已将该包全局安装，尝试的排查命令及结果：

• 运行npm bin -g返回：

Unknown command: "bin"

To see a list of supported npm commands, run:
  npm help

• 运行npm root -g返回：

/opt/homebrew/lib/node_modules

• 运行which scaffold返回：

/opt/homebrew/bin/scaffold

• 运行npm list -g project-scaffold返回：

/opt/homebrew/lib
└── project-scaffold@1.1.1

解决步骤 #

1. 检查脚本的shebang头 #

确保index.js文件最顶部添加了Node.js的shebang声明，这是系统识别脚本运行环境的关键：

#!/usr/bin/env node

注意这一行必须位于文件第一行，不能有任何前置空格或字符。

2. 验证文件执行权限 #

检查原文件和软链接的权限是否包含可执行权限：

# 查看项目中index.js的权限
ls -l /opt/homebrew/lib/node_modules/project-scaffold/index.js
# 查看全局软链接的权限
ls -l /opt/homebrew/bin/scaffold

如果没有执行权限，执行以下命令添加：

chmod +x /opt/homebrew/lib/node_modules/project-scaffold/index.js

3. 确认Node.js路径可用性 #

如果#!/usr/bin/env node无法识别Node，可直接指定本地Node的绝对路径。先用以下命令查看Node路径：

which node

然后将shebang替换为对应路径，例如：

#!/opt/homebrew/bin/node

4. 重新安装或链接包 #

先卸载全局包再重新安装，确保软链接和配置正确：

npm uninstall -g project-scaffold
npm install -g project-scaffold

如果是本地开发阶段，可重新链接包：

cd 你的项目根目录
npm unlink -g
npm link

5. 检查package.json配置完整性 #

确认package.json中没有配置冲突，比如main字段指向的文件是否正确，同时确保包名project-scaffold未与现有npm包重名（当前安装状态已成功，此问题概率较低）。

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