为什么NPM安装docma后未自动配置cmdlet，命令无法执行且无node_modules文件夹？

核心根因排查 #

• 先确认node_modules不存在的原因：npm默认的本地安装规则是只在你执行npm install的当前工作目录下生成node_modules文件夹，如果你之前没有在目标项目目录下执行本地安装，而是用了全局安装，项目目录下本来就不会存在对应docma的node_modules文件夹。
• 若你执行的是全局安装npm install -g docma，可执行npm root -g查询npm全局依赖的实际存储路径，进入该路径检查是否存在完整的docma包文件夹，确认安装是否真的完成。
• 跨Windows、Linux都出现命令识别失败的情况，大概率是安装流程静默中断：如果执行全局安装时，Windows端没有用管理员权限打开终端、Linux端没有加sudo提权，npm不会抛出高优先级的报错提示，只会把安装失败的日志写入debug文件，表面显示安装流程走完，实际包文件根本没有下载完整，自然不会生成可执行命令的软链接。

命令识别异常的针对性修复 #

• 检查npm全局可执行路径是否已加入系统PATH环境变量：执行npm config get prefix获取全局安装的命令存放路径，确认该路径是否在系统PATH列表中。如果路径未加入环境变量，哪怕全局包安装成功，终端也无法识别docma、docma serve这类命令。
  • Windows常见坑点：nodejs默认的全局命令存放路径通常在当前用户的AppData隐藏目录下，新装node环境时该路径不会自动加入用户环境变量，就会触发“不是有效cmdlet”的报错。
  • Linux常见坑点：如果是通过系统源安装的nodejs，全局包的可执行文件如果因为权限问题没有创建软链接到/usr/local/bin，当前shell就会报命令不存在。
• 若环境变量配置正确仍无法识别命令，可以绕过自动软链接机制：找到全局目录下docma包的bin入口文件，直接用node执行验证，命令格式为node 全局路径/docma/bin/docma.js，如果能正常输出版本信息，说明包本身完好，只需要在全局命令路径下手动创建指向该入口文件的软链接，即可正常调用docma命令。

额外提醒 #

因为docma已多年无维护更新，依赖的第三方组件存在已知安全漏洞，且对新版nodejs的语法兼容性较差，就算成功跑通命令，后续文档构建环节也很容易碰到兼容报错。如果经过以上排查仍无法正常使用，可以直接替换为同功能且长期维护的文档生成工具，避免在停更工具的兼容问题上消耗时间。

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