Storybook v6.5.9渲染React/MUI组件时Controls页不显示描述与默认值

架构老林

2026-8-27

问题场景

使用Storybook v6.5.9渲染React/MUI组件时，核心功能运行正常，但存在属性展示异常：

Canvas页面的Controls标签页下，组件属性的描述说明、默认值无法正常渲染
切换到Docs标签页后，属性描述信息可以正常展示
未对Storybook默认导出项添加额外配置，也未修改任何开箱即用的默认参数。

修复方案

这个问题是TS类型解析规则不匹配导致的，按以下步骤操作即可修复：

打开项目根目录下.storybook/main.js（或main.ts）配置文件
添加/修改typescript字段配置，指定docgen解析规则，强制提取属性注释与默认值，参考配置如下：

module.exports = {
  // 保留原有其他配置项，比如stories、addons等
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      shouldRemoveUndefinedFromOptional: true,
      // 过滤node_modules里第三方组件的冗余属性，只解析当前项目自定义组件的props
      propFilter: (prop) => {
        if (prop.parent?.fileName) {
          return !prop.parent.fileName.includes('node_modules')
        }
        return true
      }
    }
  }
}

检查组件写法：
- 函数组件的属性默认值直接写在参数解构的默认赋值位置，不要通过静态Component.defaultProps属性声明，后者在TS类型推导下经常无法被docgen正确识别
- 属性描述直接写在Props类型定义的JSDoc注释里，不要在复杂的交叉类型、Pick/Omit嵌套推导上写注释，会导致解析失败
配置修改完成后，完全终止Storybook运行进程，删除项目下node_modules/.cache缓存目录，重新执行启动命令即可，热重载不会刷新docgen的解析结果，必须冷启动生效。