日常工作知识库

Appearance

npm link 后 CLI 报错 — node_modules 缺失导致 MODULE_NOT_FOUND ​

归类：CLI / npm
发生时间：2026-03-06
状态：✅ 已解决

一、问题现象 ​

执行全局 CLI 命令（如 mds）时报错：

Error: Cannot find module 'commander'
Require stack:
- /path/to/workspace/mds-cli/dist/cli
code: 'MODULE_NOT_FOUND'

二、根本原因 ​

CLI 是通过 npm link 注册到全局的，npm link 会在全局 bin 目录创建一个符号链接指向本地源码目录：

~/.nvm/versions/node/v20.20.0/bin/mds
  → ../lib/node_modules/@mdsfe/mds-cli   (symlink)
    → ~/workspace/mds-cli                (本地源码)

但本地源码目录没有安装依赖（缺少 node_modules），导致运行时 require('commander') 找不到模块。

与 npm install -g 的区别：

方式说明
npm install -g将包（含依赖）复制到全局 node_modules，独立运行
npm link在全局创建符号链接指向本地源码，依赖由本地 node_modules 提供

三、排查过程 ​

bash
# 确认 mds 的全局链接指向
readlink ~/.nvm/versions/node/v20.20.0/lib/node_modules/@mdsfe/mds-cli
# → ../../../../../../../workspace/mds-cli（本地目录）

# 确认依赖状态
npm ls commander
# └── (empty)  ← 依赖未安装

四、修复方案 ​

bash
# 进入本地源码目录
cd ~/workspace/mds-cli

# 安装依赖
npm install

# 全局安装（将本地包含已安装依赖注册到全局）
npm install -g .

# 验证
mds --version

五、预防建议 ​

  1. npm link 适合开发调试，需确保本地 node_modules 存在
  2. 换机或克隆仓库后，必须先 npm install 再 npm link
  3. 发布供他人使用的工具，优先用 npm install -g 或发布到 registry 让用户安装
  4. 可用 npm ls 快速确认依赖是否完整，出现 UNMET DEPENDENCY 即需重新安装