在日常开发中，Trae 是个很不错的辅助工具，能帮我们自动生成组件的 Storybook 文档，省下不少写枯燥注释的时间。但有时候，它也会闹点小脾气——对着你的 React 组件，死活憋不出一句有用的文档。这时候别急着上火，问题大概率出在下面这几个地方，我们按顺序排查一遍基本就能解决。
一、检查组件导出与默认导出一致性
Trae 这款工具挺“认生”的，它只认组件是不是有明确的默认导出（比如 export default MyComponent）。如果你的组件用的是命名导出（比如 export const MyComponent = ...），或者一个文件里导出了好几个东西，它就会彻底懵掉，不知道该拿谁开刀，props 和文档自然也就无从谈起了。
解决方案很简单：
- 打开目标组件文件，比如
Button.tsx。 - 确认文件里只有一个 export default 语句指向了你要处理的组件。
- 把文件里其他的 export const 或 export function 都去掉，或者把它们变成普通的内部函数。稍微整理下文件结构，保持“干净”，Trae 才能准确“下刀”。
二、补充 TypeScript 类型定义与 JSDoc 注释
Trae 虽然聪明，但它也不是算卦的。它需要明确的类型信息来生成参数说明。如果没有定义 props 的类型，比如一个清晰的 interface ButtonProps，那文档里的控件选项肯定就是空的。
这里有两个关键动作：
- 定义清晰的 Props 类型，例如：
interface ButtonProps { children: string; variant?: 'primary' | 'secondary'; onClick?: () => void; } - 给这个接口加上完整的 JSDoc，最好为每个属性都写上 @param 标注，比如
/** @param children 按钮显示文本 */。然后，让组件的函数签名显式地引用这个类型：const Button: FC= ({ children, variant, onClick }) => { ... };
这一步做好了，Trae 就能清晰地知道你的组件想要什么，文档自然就充实了。
三、验证 Trae 配置中的组件路径匹配规则
如果前两步都没问题，那很可能是个“找不到人”的问题。Trae 默认会扫描特定目录下的文件，比如 src/components/**/*.{ts,tsx}。但如果你把组件放在了如 src/ui/Button.tsx 这种“非主流”位置，Trae 就会“视而不见”。
解决办法是去项目根目录下，找到 Trae 的配置文件（通常叫 trae.config.js 或 .traerc）。检查里面的 componentsPattern 字段，看看它的 glob 匹配规则是不是覆盖了你组件的真实路径。如果不对，就把它改成更宽泛或更精确的路径，比如 "src/**/components/**/*.{ts,tsx}" 就能覆盖到更多子目录。
四、手动触发 Trae 的类型推导重载
有时候 Trae 只是有点“缓存”上的小毛病，并不是真的卡住了。我们可以强制它刷新一下。
在终端里先执行 npx trae --clear-cache 清除本地缓存，然后再执行 npx trae --generate 手工启动文档生成流程。接着，观察控制台输出，留意有没有出现类似 "Resolved props for Button" 这样的日志。如果还是提示 "No props inferred"，那基本可以确定是第二步的类型定义出了问题，得回去再仔细查查。
五、降级使用 CSF 3 显式 stories 文件回退方案
如果前面所有方法都试过了，Trae 还是“油盐不进”，那也别死磕。我们可以“曲线救国”——绕过它的自动生成逻辑，自己动手写一个标准的 Storybook 故事文件。
操作起来也不复杂：
- 在组件同级目录下新建一个
Button.stories.tsx文件。 - 写入一段最精简的 CSF 3 代码结构：
import { Meta, StoryObj } from '@storybook/react'; import { Button } from './Button'; const meta = { component: Button } satisfies Meta; export default meta; export const Primary: StoryObj = { args: { children: '点击我', variant: 'primary' } }; - 保存后重启 Storybook 服务（
npm run storybook），看看右边 Controls 面板里，variant和children控件是不是已经乖乖出现了。
这算是个兜底方案，虽然多写了几行代码，但能确保文档功能不受影响。其实手动编写 stories 文件本身也是前端工程师的必备技能，值得掌握。
