Next.js App Router下styled-components组件库Hydration异常求助

核心问题分析 #

你遇到的两个问题本质都是styled-components实例重复或解析异常：

1. 初始peerDependency方案报错：组件库输出格式或Next.js编译配置未正确处理peer依赖，导致服务端无法解析styled-components导入
2. 直接依赖方案的hydrate问题：组件库打包了独立的styled-components实例，与Next.js项目中的实例生成的类名不匹配，客户端无法正确匹配服务端渲染的样式

正确解决方案（回归peerDependency模式） #

组件库使用peerDependency是标准做法，只需调整配置让Next.js正确识别并编译组件库代码：

1. 组件库侧配置 #

package.json（明确peer依赖）

{
  "name": "skafte-cms",
  "peerDependencies": {
    "styled-components": "^6.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "styled-components": "^6.0.0" // 仅开发环境安装
  }
}

Rollup配置（确保不打包peer依赖，输出ES模块）

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  output: [
    {
      file: 'dist/index.js',
      format: 'esm', // 必须输出ES模块，适配Next.js的模块解析
      sourcemap: true,
    },
  ],
  external: ['react', 'react-dom', 'styled-components'], // 将peer依赖标记为外部依赖，不打包进组件库
  plugins: [
    resolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json' }),
  ],
};

2. Next.js侧配置 #

next.config.js（添加组件库转译）

/** @type {import('next').NextConfig} */
const nextConfig = {
  compiler: {
    styledComponents: {
      cssProp: true,
    },
  },
  transpilePackages: ['skafte-cms'], // 让Next.js编译组件库代码，确保styled-components语法被正确处理
}

module.exports = nextConfig

简化StyledComponentsRegistry（单实例管理）

不需要维护两个样式表，整个应用共用一个styled-components实例即可：

'use client';

import React, { useState } from 'react';
import { useServerInsertedHTML } from 'next/navigation';
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';

export default function StyledComponentsRegistry({ children }) {
  const [sheet] = useState(() => new ServerStyleSheet());

  useServerInsertedHTML(() => {
    const styles = sheet.getStyleElement();
    sheet.instance.clearTag();
    return styles;
  });

  if (typeof window !== 'undefined') return <>{children}</>;

  return (
    <StyleSheetManager sheet={sheet.instance}>
      {children}
    </StyleSheetManager>
  );
}

方案说明 #

1. peerDependency的必要性：避免组件库和主应用同时打包styled-components，消除多实例导致的类名不匹配问题
2. transpilePackages的作用：组件库的代码未经过Next.js编译器处理，直接引入会导致服务端无法解析styled-components的语法糖，添加转译后可确保语法被正确转换
3. 单实例样式管理：整个应用共用一个styled-components实例，服务端生成的类名与客户端完全一致，解决hydrate不匹配的问题

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