Next.js下按组件拆分Webpack+React组件库解决SSR报错

问题背景 #

过去一年半团队基于Storybook、React、Webpack 5开发了内部组件库，近期在Next.js项目中接入该组件库时遇到SSR兼容问题：

• Next.js同时支持服务端渲染与客户端渲染，组件库（含其第三方依赖）中存在window、document、self等仅客户端可用的对象调用，全量导入时会触发self is not defined类SSR报错
• 即便仅导入不依赖客户端API的基础组件（如Button）也会触发该错误，验证单组件导入时仍会加载全量库代码
• 若全量使用动态导入解决报错，会带来加载耗时增加、首屏内容缺失的问题，甚至库内的加载态组件本身也需要动态导入，使用体验较差

预期目标 #

组件库需支持三种导入方式，将客户端API调用隔离到对应组件内，尽可能减少动态导入的使用：

1. 全量导入：import { Component } from 'Library'，供非Next.js场景使用
2. 分类导入：import { Component } from 'Library/ComponentCategory'，如表单类组件统一导入，仅加载分类所需代码，无客户端依赖的分类可直接在SSR环境使用
3. 单组件导入：import { Component } from 'Library/Component'，仅加载单个组件所需代码，仅对依赖客户端API的组件做动态导入，无需全库动态加载

已验证无效的方案 #

• 客户端对象兼容处理：移除自有代码中不必要的客户端对象引用，对无法移除的逻辑添加if (typeof window !== 'undefined')判断，但第三方依赖中仍存在客户端对象调用，无法完全规避
• Webpack代码分割配置：配置多入口（主入口、组件分类入口、单组件入口），设置UMD输出格式，配合splitChunks、runtimeChunk做代码分割，dist目录已生成对应分块文件，但导入单组件时仍触发全量相关的SSR报错
• Next.js配置适配：引入next-transpile-modules转译组件库，添加服务端fs模块fallback配置，未解决问题
• 构建配置调整：确认已使用MiniCssExtractPlugin提取CSS（未使用style-loader做运行时注入），测试关闭SCSS文件复制逻辑、替换Rollup作为打包器，均未解决问题
• 备选方案评估：考虑过Lerna做微库拆分，但改造成本高、维护复杂度大；放弃使用Next.js的方案不符合技术选型预期，已排除

当前临时采用全量动态导入的方案兜底，以下是可落地的根治方案：

落地方案 #

1. 修正组件库导出配置，解决按需导入失效 #

单组件导入仍加载全量代码的核心原因是模块解析规则未对齐，和打包器选择无关，按以下配置修复即可：

• 在组件库package.json中添加exports字段，明确映射三类导入路径，同时配置sideEffects标记无副作用文件，支持下游打包器做tree-shaking：

{
  "name": "Library",
  "main": "./dist/index.umd.js",
  "module": "./dist/index.esm.js",
  "types": "./dist/types/index.d.ts",
  "sideEffects": ["**/*.css", "**/*.scss"],
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.umd.js"
    },
    "./*": {
      "import": "./dist/*/index.esm.js",
      "require": "./dist/*/index.umd.js"
    }
  }
}

• 构建ESM格式产物时，关闭模块合并配置（Webpack中设置optimization.concatenateModules: false，Rollup中关闭模块合并相关逻辑），保留原始import/export语句，不要把所有模块打包成单文件，给下游打包器留足tree-shaking空间。
• 每个分类、单组件的入口文件仅导出对应模块的代码，不要在入口顶层引入全量样式、全量工具函数，避免隐式依赖导致全量代码被加载。

2. 分层隔离客户端API调用 #

不需要修改第三方依赖源码，从两个层面隔离客户端调用：

• 构建组件库时，对强依赖浏览器API的第三方依赖（如DOM计算、事件监听、动画相关库），不要打包进组件产物，标记为peerDependencies，由下游项目统一做依赖解析，避免依赖顶层的客户端对象调用在SSR阶段执行。
• 对必须内置的带客户端调用的依赖，不要在组件文件顶层import，仅在组件的客户端生命周期（React useEffect、用户事件回调）中动态加载：

// 错误写法：顶层引入，SSR执行时直接触发依赖内的window调用
import ClientTool from 'some-client-lib'
const ClientComp = () => <div>{ClientTool.text}</div>

// 正确写法：仅在客户端侧加载依赖
const ClientComp = () => {
  const [libData, setLibData] = useState(null)
  useEffect(() => {
    import('some-client-lib').then(mod => setLibData(mod.default.text))
  }, [])
  return libData ? <div>{libData}</div> : <Spinner />
}

3. Next.js侧最小范围客户端标记 #

不需要全量动态导入组件库，仅对确实依赖客户端API的组件做特殊处理：

• Next.js 13+ App Router场景下，在依赖客户端API的组件文件顶部添加'use client'指令，这类组件可直接导入使用，不需要额外包裹动态导入。
• 对SSR阶段完全无法渲染的重型客户端组件（如富文本编辑器、3D渲染组件），使用Next.js dynamic API时关闭SSR即可，无客户端依赖的基础组件（Button、Typography、栅格布局等）直接在服务端组件中导入即可正常渲染：

import dynamic from 'next/dynamic'
// 仅重型组件做关SSR的动态导入
const HeavyEditor = dynamic(() => import('Library/RichEditor'), {
  ssr: false,
  loading: () => <Library.Spinner />
})

验证步骤 #

配置完成后做两步校验，确认问题解决：

1. 组件库构建完成后，用source-map-explorer分析单组件入口的产物，确认产物中不包含其他无关组件、无关依赖的代码
2. 在Next.js项目中单独导入Button组件执行生产构建，确认服务端构建阶段不触发self/window is not defined报错，Button组件代码出现在首屏chunk中，不需要等待客户端动态加载

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