如何使用tsup打包独立的Tailwind CSS v4组件且不与宿主应用样式冲突？

阿华AIGC实验室

2026-4-7

我之前也碰到过一模一样的问题！用Tailwind v4做共享组件库，全局CSS一导入就把宿主应用的样式搅得一团糟，折腾了好一阵才找到靠谱的解决办法。核心思路就是把组件的样式完全局部化，不让全局主题、工具类污染宿主环境，同时让用户导入组件时样式自动生效，不用手动加CSS导入。下面是我亲测有效的方案：

一、核心问题拆解

你现在的globals.css是全局注入的：@import 'tailwindcss'会把Tailwind的所有基础样式、工具类全塞到宿主的全局环境里，自定义的@theme和@utility也是全局生效的——这就等于你的组件库直接修改了宿主的Tailwind配置，不冲突才怪！所以必须把这些样式限制在组件自己的“地盘”里。

二、推荐方案：CSS Modules + 组件级Tailwind导入

CSS Modules会自动把你的类名哈希化（比如footer变成Footer__footer___abc123），完全隔离组件样式和宿主的全局样式，同时Tailwind v4支持在单个CSS文件里局部导入，完美适配这个场景。

1. 重构组件样式文件

先删掉全局的globals.css，给每个组件单独创建CSS Modules文件（文件名以.module.css结尾）。比如给Footer组件写Footer.module.css：

/* 局部导入Tailwind，仅在当前组件样式文件生效 */
@import 'tailwindcss';

/* 组件专属的主题变量，不会污染全局 */
@theme {
  --color-primary: #ffde00;
  --color-dark-gray: #222222;
}

/* 组件专属的工具类，仅在当前组件可用 */
@utility responsive-pad {
  @apply px-6 xs:px-8 sm:px-12 lg:px-16;
}

/* 组件的样式类，会被CSS Modules哈希化 */
.footer {
  @apply bg-black text-white;
  @apply responsive-pad; /* 用自定义工具类 */
}

.footerTitle {
  @apply text-3xl font-bold;
}

然后修改Footer.tsx，导入这个CSS Modules并使用哈希化的类名：

import styles from './Footer.module.css';

export function Footer() {
  return (
    <footer className={styles.footer}>
      <p className={styles.footerTitle}>Ready to get started?</p>
    </footer>
  );
}
export default Footer;

2. 配置tsup和PostCSS处理CSS

tsup默认不处理CSS，得配置它用PostCSS编译Tailwind和CSS Modules：

第一步：安装依赖

把这些工具装到开发依赖里（发布包时不需要宿主安装它们）：

npm install -D postcss postcss-import tailwindcss

第二步：创建PostCSS配置文件

在项目根目录新建postcss.config.js：

export default {
  plugins: {
    'postcss-import': {}, // 处理CSS里的@import
    tailwindcss: {}, // 编译Tailwind语法
  },
};

第三步：修改tsup配置

更新tsup.config.ts，启用CSS处理和CSS Modules：

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/exports-server.ts', 'src/exports-client.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: true,
  sourcemap: true,
  clean: true,
  external: [
    'react',
    'react-dom',
    '@tryghost/admin-api',
    '@tryghost/content-api',
  ],
  outDir: 'dist',
  tsconfig: './tsconfig.build.json',
  // 新增CSS处理配置
  css: {
    modules: {
      // 自定义哈希类名格式，方便调试
      generateScopedName: '[name]__[local]___[hash:base64:5]',
    },
    postcss: true, // 启用PostCSS
  },
});

3. 调整package.json

把Tailwind、PostCSS相关依赖移到devDependencies，确保发布时不打包它们：

{
  "devDependencies": {
    "postcss": "^8.4.38",
    "postcss-import": "^16.1.0",
    "tailwindcss": "^4.0.0",
    "tsup": "^8.0.2",
    // 其他开发依赖...
  },
  "dependencies": {
    // 只保留react、react-dom等运行时依赖
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

三、备选方案：用`:scope`伪类局部作用域

如果你不想用CSS Modules，也可以用CSS的:scope伪类把组件样式限定在组件内部，写法更简单，但兼容性略差（现代浏览器都支持）：

给Footer创建Footer.css：

:scope {
  @import 'tailwindcss';
  
  @theme {
    --color-primary: #ffde00;
    --color-dark-gray: #222222;
  }

  @utility responsive-pad {
    @apply px-6 xs:px-8 sm:px-12 lg:px-16;
  }

  /* 样式只作用于当前组件的元素 */
  footer {
    @apply bg-black text-white responsive-pad;
  }

  footer p {
    @apply text-3xl font-bold;
  }
}

在Footer.tsx里导入这个CSS：

import './Footer.css';

export function Footer() {
  return (
    <footer>
      <p>Ready to get started?</p>
    </footer>
  );
}
export default Footer;