Storybook 7切换故事失败：缺失“storybook-docs”元素报错

问题描述 #

升级Storybook从v6到v7.6.4（同步升级Next.js和React大版本）后，所有故事能正常渲染，但切换故事时必须刷新页面才能加载新组件，控制台抛出以下错误：

TypeError: Cannot read properties of null (reading 'setAttribute')

错误来自sb-preview runtime.js中的代码this.docsRoot().setAttribute("hidden", "true")，原因是找不到id为storybook-docs的DOM元素。

排查与修复步骤 #

1. 调整Docs插件的加载顺序 #

把@storybook/addon-docs移到@storybook/addon-essentials前面加载，避免essentials的默认配置覆盖docs的DOM初始化逻辑：

// .storybook/main.ts
addons: [
  "@storybook/addon-links",
  "@storybook/addon-docs", // 移到essentials之前
  "@storybook/addon-essentials",
  // ...其他插件配置
]

2. 强制生成Docs所需DOM容器 #

在.storybook/preview.ts中添加参数配置，强制Storybook渲染storybook-docs容器：

export const parameters = {
  docs: {
    container: ({ children }) => <div id="storybook-docs">{children}</div>,
    disable: false, // 确保Docs模式未被禁用
  },
};

3. 彻底清理缓存并重建 #

升级后残留的缓存可能导致DOM结构异常，执行以下命令清理：

# 清理Storybook缓存
npx storybook clean
# 清理Next.js缓存
rm -rf .next
# （可选）重新安装依赖，排除版本冲突
rm -rf node_modules package-lock.json
npm install

4. 检查自定义HTML模板 #

如果项目自定义了Storybook的HTML模板（比如preview-head.html），确保没有删除默认的storybook-docs容器，需保留如下结构：

<!-- 在模板中保留该容器 -->
<div id="storybook-docs"></div>

5. 排查样式插件冲突 #

当前配置中的@storybook/addon-styling-webpack可能与Storybook内部DOM处理逻辑冲突，先临时注释掉该插件，验证问题是否消失。如果是，调整插件的CSS规则，避免覆盖Storybook的基础DOM结构样式。

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