Rollup打包styled-components组件库useDebugValue空值错误排查

TypeError: Cannot read property 'useDebugValue' of null 是典型的React多实例+依赖打包错误：styled-components内部依赖React的useDebugValue Hook，当组件库打包时把独立副本的React、styled-components打进产物，和宿主项目的React实例不共享上下文，Hook执行时拿到的React引用为null就会触发该报错。

现有配置的明确错误点 #

• Rollup主构建逻辑未声明外部依赖：你仅在dts类型生成的配置块里加了external: ['react', 'styled-components']，真正生成cjs/esm运行时代码的第一个构建块完全没配置external，导致rollup默认把react、styled-components的源码直接打包进组件库产物，直接制造多实例冲突。
• babel插件配置格式错误：babel.config.js里的babel-plugin-styled-components传参写法不符合规范，配置对象被babel识别为独立插件，styled-components的编译规则完全不生效。
• 缺少peerDependencies约束：组件库未声明对react、styled-components的宿主依赖要求，安装时容易出现多版本依赖副本共存的问题。

修复步骤 #

1. 修正rollup.config.js配置，给主构建块添加external规则和全局变量映射：

// 主构建块修改后
{
    input: 'src/index.ts',
    // 标记这些依赖为外部依赖，不打入组件库产物
    external: ['react', 'react-dom', 'styled-components'],
    output: [
        {
            file: packageJson.main,
            format: 'cjs',
            sourcemap: true,
            // 补充全局变量映射
            globals: {
                react: 'React',
                'react-dom': 'ReactDOM',
                'styled-components': 'styled'
            }
        },
        {
            file: packageJson.module,
            format: 'esm',
            sourcemap: true,
        },
    ],
    plugins: [
        resolve(),
        commonjs(),
        // 修正styled-components babel插件的传参格式
        babel({
            plugins: [
                ['babel-plugin-styled-components', {
                    namespace: 'appname-',
                    displayName: false,
                    fileName: false
                }]
            ],
            exclude: 'node_modules/**'
        }),
        typescript({ tsconfig: './tsconfig.json' }),
        postcss()
    ],
},
// dts生成配置保持原有内容即可

2. 修正babel.config.js的插件配置格式，避免babel解析插件参数失败：

module.exports = {
    presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'],
    plugins: [
        ['babel-plugin-styled-components', {
            namespace: 'appname-',
            displayName: false,
            fileName: false
        }]
    ]
};

3. 在组件库的package.json中添加peerDependencies声明，强制宿主项目提供对应版本的依赖：

{
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0",
    "styled-components": ">=5.0.0"
  }
}

如果使用styled-components v6版本，把对应版本要求改成>=6.0.0即可。

4. 本地联调时如果用npm/yarn link，必须在组件库目录执行npm link <宿主项目绝对路径>/node_modules/react和npm link <宿主项目绝对路径>/node_modules/styled-components，强制本地联调时使用宿主项目的同一份依赖实例，避免软链导致的多副本问题。

验证方式 #

重新执行打包后，检查生成的cjs/esm产物，顶部如果存在require('react')、require('styled-components')的导入语句，说明external配置生效，依赖没有被打进产物。将新包安装到宿主项目重启服务后，报错即可消除。

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