NextJS项目Storybook引入Tailwind CSS后MDX样式失效咨询

问题现象 #

搭建集成Tailwind CSS与Storybook的Next.js项目时，接入Tailwind后MDX内容样式完全失效：

• 接入Tailwind前正常效果：
• 接入Tailwind后失效效果：

已做的排查尝试 #

参考社区方案接入Tailwind时，在.storybook/main.js中加入了如下配置：

// 移除这段配置时MDX可以正常渲染，但Tailwind样式不生效
{
  name: '@storybook/addon-postcss',
  options: {
    postcssLoaderOptions: {
      implementation: require('postcss'),
    },
  },
},

配置冲突表现：保留上述配置时Tailwind生效但MDX样式丢失，移除后MDX正常但Tailwind工具类不生效。

• 项目复现代码仓库：next-storybook-demo

具体答复 #

1. 双样式共存配置步骤 #

冲突根因有两个：一是旧版@storybook/addon-postcss会覆盖Storybook（尤其是7+版本搭配Next.js框架时）内置的PostCSS与MDX处理规则，二是Tailwind默认的preflight全局样式重置会清除浏览器原生排版标签的默认样式，导致MDX渲染的内容没有基础格式。按以下步骤调整即可解决：

• 第一步：卸载多余的@storybook/addon-postcss包，使用@storybook/nextjs框架的Storybook项目已经内置PostCSS与Tailwind支持，不需要额外引入该插件：

  npm uninstall @storybook/addon-postcss
  

• 第二步：调整Tailwind全局引入配置，避免基础样式重置影响MDX排版。在.storybook目录下新建全局样式文件preview.css，写入如下内容：

  /* 按需引入Tailwind层级，若不需要全局样式重置可以不引入base层 */
  @tailwind components;
  @tailwind utilities;
  
  /* 如果需要保留Tailwind的base层重置，单独给MDX内容区补全默认排版样式即可 */
  .sbdocs-content {
    h1 { font-size: 2em; font-weight: 700; margin: 0.67em 0; }
    h2 { font-size: 1.5em; font-weight: 700; margin: 0.83em 0; }
    h3 { font-size: 1.17em; font-weight: 700; margin: 1em 0; }
    p { margin: 1em 0; line-height: 1.7; }
    ul { list-style: disc; padding-left: 2em; margin: 1em 0; }
    ol { list-style: decimal; padding-left: 2em; margin: 1em 0; }
    a { color: #2563eb; text-decoration: underline; }
    code { background: #f3f4f6; padding: 2px 6px; border-radius: 4px; font-family: monospace; }
  }
  

• 第三步：在.storybook/preview.js中全局引入上述样式文件：

  import './preview.css'
  
  const preview = {
    // 原有preview配置保持不变
  }
  export default preview
  

• 第四步：检查根目录tailwind.config.js的content配置，确保覆盖所有Storybook相关文件，包含mdx后缀：

  /** @type {import('tailwindcss').Config} */
  module.exports = {
    content: [
      './pages/**/*.{js,ts,jsx,tsx}',
      './components/**/*.{js,ts,jsx,tsx}',
      './stories/**/*.{js,ts,jsx,tsx,mdx}',
    ],
    theme: { extend: {} },
    plugins: [],
  }
  

• 第五步：清理.storybook/main.js中的旧配置，删除之前添加的addon-postcss条目，最终addons配置参考如下：

  const config = {
    stories: ["../stories/**/*.mdx", "../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
    addons: [
      "@storybook/addon-links",
      "@storybook/addon-essentials",
      "@storybook/addon-interactions",
      // 移除@storybook/addon-postcss相关配置项
    ],
    framework: { name: "@storybook/nextjs", options: {} },
    docs: { autodocs: "tag" },
  };
  export default config;
  

注意：重启前一定要删除项目下的.cache和node_modules/.cache目录，否则旧的loader配置可能残留导致问题复现，清理完成后重启Storybook即可，此时Tailwind工具类和MDX排版样式会同时正常生效。

2. 可移除的非必要插件 #

当前默认配置里的插件可以按实际需求裁剪，以下插件移除后不会影响Tailwind和MDX的核心运行：

• @storybook/addon-onboarding：仅在首次启动Storybook时展示新手引导流程，项目初始化完成后完全可以移除
• @storybook/addon-interactions：如果不需要做组件交互调试、交互流程自动化测试，可以直接移除
• 如果不需要使用Storybook的自动生成文档、组件属性面板、操作事件日志等功能，还可以将@storybook/addon-essentials拆分为单独的子插件按需引入，普通业务项目保留essentials包即可，不需要额外拆分。

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