使用JSDoc时出现FATAL: Unable to load template错误的解决方法

问题说明 #

为Next.js项目配置JSDoc时碰到两个核心问题：

• 配置"template": "./node_modules/better-docs"时，文档能生成，但better-docs提供的typescript、component等插件完全没加载生效
• 改成"template": "better-docs"后，直接抛出致命错误：

  FATAL: Unable to load template: Cannot find module 'C:\Users\...\node_modules\.pnpm\better-docs@2.7.2_prop-types@15.8.1_react-dom@18.2.0_react@18.2.0\node_modules\better-docs\publish.js/publish'
  

解决方法 #

1. 修正插件路径配置 #

better-docs的插件不需要写node_modules/前缀，直接用短名称即可，同时调整插件顺序（typescript插件建议放在最前面）：

"plugins": [
  "better-docs/typescript",
  "plugins/markdown",
  "jsdoc-mermaid",
  "better-docs/component",
  "better-docs/category",
  "better-docs/typedef-import"
]

2. 适配pnpm的模板路径问题 #

由于pnpm的依赖软链结构和npm不同，JSDoc无法正常解析短路径模板，提供两种解决方案：

方案一：开启pnpm的shamefully-hoist模式

在项目根目录的.npmrc文件中添加：

shamefully-hoist=true

然后删除node_modules和pnpm-lock.yaml，重新执行pnpm install，之后模板路径改为"template": "better-docs"即可正常加载。

方案二：直接指定publish.js完整路径

保持模板字段为相对路径，但直接指向better-docs的publish.js文件：

"opts": {
  "encoding": "utf8",
  "destination": "docs/",
  "readme": "README.md",
  "recurse": true,
  "verbose": true,
  "template": "./node_modules/better-docs/publish.js"
}

3. 验证配置是否生效 #

执行JSDoc生成命令后，检查docs/目录下的内容：

• 确认组件文档、分类等better-docs专属功能是否正常显示
• 查看控制台输出（因配置了verbose: true），确认插件已成功加载

内容的提问来源于stack exchange，提问作者Mayank Kumar Chaudhari