必须在 CSS Modules 文件顶部添加 @reference tailwindcss;，否则 @apply 因作用域隔离无法找到 Tailwind 全局工具类；该指令需置于最前、无引号、带分号，且不与 scoped 混用。
直接在 CSS Modules 文件顶部加 @reference tailwindcss，否则 @apply 会找不到 Tailwind 工具类——这不是路径或配置问题，而是作用域隔离导致的引用断链。
为什么 CSS Modules 里 @apply 报错 “Are you using CSS modules or similar and missing @reference”
CSS Modules 默认给所有类名加哈希后缀（比如 .btn → .btn_abc123），这会切断 @apply 对全局 Tailwind 类（如 bg-blue-500）的引用。Tailwind v3.3+ 引入 @reference 就是为了解决这个隔离问题。
- 报错不是因为没装插件、没配
content，而是作用域内根本“看不见” Tailwind 的全局类 -
@apply bg-blue-500本质是查找已存在的.bg-blue-500规则，而 CSS Modules 拦截了这个查找过程 - Vue 的
<style scoped>、Svelte 的:global()外部样式也属于同类机制，同样需要@reference
@reference tailwindcss 怎么写才有效
必须放在 CSS Modules 文件最顶部（任何 @import 或规则之前），且不能带分号、空格或注释干扰：
@reference tailwindcss;
@layer components {
.btn-primary {
@apply tw-bg-blue-600 tw-text-white tw-rounded tw-px-4 tw-py-2;
}
}
- ✅ 正确：
@reference tailwindcss;（结尾分号可选，但推荐加上） - ❌ 错误：
@reference 'tailwindcss';（加引号）、@reference tailwindcss（缺分号有时会解析失败）、// 注释后写 @reference（注释后不生效） - 如果项目用了 prefix（如
tw-），@reference仍指向原始类名空间，@apply写的仍是tw-bg-blue-600，不需要额外改写
不用 @reference 的替代方案（不推荐）
硬编码或复制粘贴 Tailwind 的 CSS 规则，既不可维护又易过期：
立即学习“前端免费学习笔记（深入）”；
- 把
tw-bg-blue-600对应的background-color: #2563eb;手动写进组件样式里 - 用
@import引入 Tailwind 的完整 CSS 文件（体积爆炸，且破坏作用域本意） - 关掉 CSS Modules（放弃样式隔离，风险陡增）
这些做法绕开了问题本质，反而让后续升级 Tailwind 或调整主题变得极其脆弱。
常见踩坑点：Vite + Vue + CSS Modules 组合
Vite 默认支持 CSS Modules，但 Vue 单文件组件里的 <style module> 需要显式启用，且 @reference 必须写在 <style> 标签内部最顶行：
<style module>
@reference tailwindcss;
.btn {
@apply tw-p-2 tw-rounded;
}
</style>
- ⚠️ 不要写在
<script setup>里，也不要在<style scoped>中混用（scoped和module是互斥的） - ⚠️ 如果用了
defineClass或useCssModule，确保 JS 中引用的类名和 CSS 文件里定义的一致，@reference不影响运行时类名生成 - ? 提示：VS Code 插件 “Tailwind CSS IntelliSense” 在启用
@reference后能正确补全工具类，这是验证是否生效的最快方式
真正麻烦的不是加这一行，而是忘记它——只要用了 @apply，就必须面对作用域隔离这层墙。
