npm link 关联失效或私有源安装 404 排查

归类：cli / nodejs 发生时间：2026-03-17 状态：✅ 已解决

---

一、问题现象 / 背景

1. 执行 sudo npm i -g @mdsfe/mds-cli 时报错 404 Not Found，涉及依赖 @vue/cli-shared-utils。
2. 虽然报错，但本地源码目录执行 mds 提示 zsh: command not found: mds。
3. 执行 yarn link 成功，但运行命令时仍有异常或版本信息不匹配。

二、排查过程

1. 网络诊断：发现项目使用私有 npm 源 http://private-registry.example.com/repository/npm/，该源未代理或缺少公共包 @vue/cli-shared-utils。
2. 结构检查：检查 package.json 中的 bin 配置，指向的是 ./dist/cli 而非原始的 bin/cli.js。
3. 产物验证：发现 dist 目录下的产物是经过混淆的，且需要通过脚本重命名和授权。

三、根本原因

1. 依赖缺失：私有 npm 仓库配置不全，导致全局安装失败。
2. 构建顺序：该 CLI 的 bin 映射到了构建产物 dist/cli。如果未执行构建脚本（npm run output），bin 目录虽然存在链接但指向的是空或不存在的文件，导致命令无法识别。
3. 软链不完整：npm install 失败会导致全局 bin 映射未建立。

四、解决方案

1. 安装本地依赖（跳过错误的私有源地址，确保公共依赖完整）：

   npm install --registry=https://registry.npmjs.org/

2. 生成构建产物（这是关键，否则 mds 命令找不到入口文件）：

   npm run output

   注：此命令内部执行了 obfuscate (混淆) 和 rename (重命名并 chmod +x)。
3. 本地建立全局链接：

   yarn link  # 或 npm link

五、预防建议

1. 在 package.json 的 scripts 中增加 prepare 钩子，确保在安装或 link 时自动构建产物。
2. 在私有源安装失败时，优先检查 .npmrc 配置和依赖包的可访问性。
3. 开发建议：在开发环境下，可以将 bin 暂时指向 bin/cli.js 以便直接调试，发布前再切回 dist/cli。