React 18项目用@component生成JSDoc文档遇依赖问题求助

一、修复better-docs适配React 18的方案 #

1. 强制解决依赖冲突 #

不用降级React，直接在package.json中添加overrides字段，强制让better-docs使用你的React 18版本：

{
  // 其他配置...
  "overrides": {
    "better-docs": {
      "react": "^18.2.0",
      "react-dom": "^18.2.0"
    }
  }
}

然后重新执行安装命令：

npm install better-docs

这种方式比--legacy-peer-deps更可靠，能保证依赖树的一致性，同时绕过peer版本限制。

2. 修复组件不显示问题 #

你用--legacy-peer-deps安装后组件未显示，大概率是配置或使用问题，检查以下几点：

• 修正source排除规则：你的jsdoc.conf.json中exclude字段有语法错误："./src/**/*.text,tsx"应该改为"./src/**/*.test.tsx"，否则会错误排除所有tsx文件，导致组件不被解析。
• 检查@component装饰器格式：确保组件上方的JSDoc注释正确使用@component标签，示例：

/**
 * @component
 * @description 这是一个示例React组件
 * @param {string} title - 组件标题
 */
export const DemoComponent = ({ title }) => {
  return <h1>{title}</h1>;
};

• 验证插件加载：确认jsdoc.conf.json的plugins数组中，better-docs的插件路径正确，无拼写错误。
• 查看详细日志：运行npm run docs时，利用你配置的"verbose": true查看控制台输出，确认目标组件文件是否被JSDoc扫描到，以及@component标签是否被识别。

二、替代文档生成工具（如果better-docs仍无法正常工作） #

如果上述方案无效，推荐以下适配React 18的主流工具：

• Storybook：React生态最流行的组件文档工具，支持交互式组件预览、自动生成props文档，兼容React 18，同时集成组件测试、视觉回归检测等功能，配置简单，社区资源丰富。
• TypeDoc：针对TypeScript项目的文档生成工具，可直接从TS类型定义和JSDoc注释生成结构化文档，配合typedoc-plugin-react-docgen插件，能自动解析React组件的props、状态等信息，无需额外装饰器。
• React Styleguidist：基于Webpack和React构建，支持JSDoc注释，能生成带示例的交互式组件文档，适配React 18，配置灵活，适合需要自定义文档样式的场景。

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