Vite构建的Tailwind v4组件库CSS变量在外部项目不生效

核心问题 #

组件库内部使用Tailwind v4的@theme定义的自定义颜色变量，在外部Vite项目中无法识别，本质原因是：

1. 组件库导出的是未编译的src/global.css源文件，外部项目未配置Tailwind处理该文件，导致@theme指令无法被解析为实际CSS变量；
2. Vite库模式下将tailwindcss设为外部依赖，组件库未把编译后的主题变量打包进产物，依赖外部项目的Tailwind环境但未传递主题配置。

解决方案一：将编译后的主题变量打包进组件库产物 #

1. 调整组件库Vite配置 #

修改vite.config.js，移除tailwindcss的外部依赖配置，确保Tailwind编译后的CSS被打包进产物：

export default defineConfig({
  // ...其他配置
  build: {
    rollupOptions: {
      external: [...Object.keys(peerDependencies).filter(key => key !== 'tailwindcss')],
      output: {
        banner: "\"use client\";", // 修正转义问题，直接用双引号
        globals: {
          react: 'React',
          'react/jsx-runtime': 'react/jsx-runtime',
          'react-dom': 'ReactDOM',
          // 移除tailwindcss的global配置
        },
      },
    },
  },
});

2. 确保全局样式被导入到入口文件 #

在组件库的src/main.ts中导入global.css，让Vite打包时将其纳入产物：

import './global.css';
// 导出你的组件
export { Button, Card } from './components';

3. 修改package.json导出编译后的样式 #

组件库打包后会生成单独的CSS文件（默认是dist/style.css），修改exports指向该文件：

"exports": {
  ".": "./dist/main.js",
  "./styles": "./dist/style.css",
  "./types": "./dist/main.d.ts"
},

4. 外部项目使用方式 #

在外部项目中导入组件库的样式：

import 'your-component-lib/styles';
import { Button } from 'your-component-lib';

解决方案二：让外部项目继承组件库的Tailwind主题 #

1. 组件库单独导出Tailwind配置 #

创建tailwind.config.ts文件，用Tailwind标准配置方式定义自定义颜色：

export default {
  theme: {
    extend: {
      colors: {
        'brand-orange': {
          900: 'hsla(38, 96%, 45%, 1)',
          100: 'hsla(38, 90%, 85%, 1)',
        },
      },
    },
  },
};

2. 组件库package.json导出配置文件 #

"exports": {
  ".": "./dist/main.js",
  "./tailwind-config": "./tailwind.config.ts"
},

3. 外部项目继承配置 #

在外部项目的tailwind.config.ts中导入组件库的配置作为预设：

import componentLibConfig from 'your-component-lib/tailwind-config';

export default {
  presets: [componentLibConfig],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // 如果组件库的组件是源码引入，需要添加组件库的文件路径
    './node_modules/your-component-lib/**/*.{js,ts,jsx,tsx}'
  ],
  // 外部项目自身的Tailwind配置
};

验证要点 #

• 组件库打包后，检查dist/style.css中是否包含:root下的--brand-orange-900等CSS变量；
• 外部项目引入后，通过浏览器开发者工具查看元素样式，确认CSS变量已生效。

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