基于webpack+Tailwind+Storybook的UIKit包在NextJS报document未定义如何解决？

错误根因 #

• ReferenceError: document is not defined：你的webpack配置未单独抽离CSS，样式默认被打包进JS文件，运行时会自动向document注入style标签加载样式。Next.js存在服务端渲染(SSR)阶段，服务端环境无document全局对象，因此触发报错。
• this.getOptions is not a function：你的项目依赖webpack 4.44.2，直接安装的最新版mini-css-extract-plugin仅兼容webpack 5+，版本不匹配导致API调用失败。

具体修复步骤 #

1. 安装适配webpack 4的mini-css-extract-plugin版本 #

执行以下命令安装对应版本：

yarn add mini-css-extract-plugin@1.6.2 --dev
# 或使用npm
npm install mini-css-extract-plugin@1.6.2 --save-dev

2. 调整webpack.production.js配置 #

修改生产环境配置，用mini-css-extract-plugin抽离单独CSS文件，避免样式注入逻辑：

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  mode: 'production',
  // 新增抽离CSS的插件
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'index.css'
    })
  ],
  module: {
    rules: [
      {
        test: /\.(scss)$/,
        use: [
          // 用MiniCssExtractPlugin的loader替换style注入逻辑
          MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader',
          'sass-loader',
        ],
      },
    ],
  },
};

3. 接入Next.js项目时引入全局样式 #

重新打包发布你的npm包后，在Next.js项目的入口文件（通常为_app.tsx/_app.js）中全局引入抽离出的CSS：

import 'grace/lib/index.css'

可选优化 #

如果你的其他组件存在直接操作document/window的逻辑，需要将这部分代码放在useEffect、componentDidMount等仅在客户端执行的生命周期钩子中，避免服务端运行时报错。你当前提供的Button组件无此类逻辑，无需修改。

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