Gatsby v4+需手动配置PostCSS集成Tailwind，废弃插件会导致类名失效；dark模式须在html标签添加dark类；Tailwind类应写在JSX的className中，避免CSS Modules混用和动态拼接。
不能只装 Tailwind 就完事——Gatsby 的 CSS 处理链会绕过 tailwind.config.js，导致类名不生效、响应式断点失效、暗黑模式类被忽略。
为什么 gatsby-plugin-tailwindcss 已废弃且危险
该插件在 Gatsby v4+ 中早已停止维护，它强行劫持 Webpack 的 CSS 规则，与 Gatsby 自带的 CSS Modules（.module.css）和全局样式注入逻辑冲突。常见表现：
- 开发时热更新失效，改了
tailwind.config.js必须全量重启 -
@layer或@apply在.css文件里被忽略 - 暗黑模式切换后，
dark:text-gray-300类完全不渲染 - 构建产物中缺失大量响应式类（如
md:flex），因为 PurgeCSS 误删
正确路径是：绕过所有插件，用原生 PostCSS 集成。
必须手动配置 postcss.config.js 和 tailwind.config.js
Gatsby v4+ 默认启用 PostCSS，但不会自动加载 Tailwind 插件。你得显式声明：
立即学习“前端免费学习笔记（深入）”；
在项目根目录新建 postcss.config.js：
module.exports = {
plugins: [
'postcss-import',
'tailwindcss',
'postcss-preset-env',
'autoprefixer',
],
}
同时确保 tailwind.config.js 的 content 字段覆盖 Gatsby 的实际路径：
- 必须包含
./src/**/*.{js,jsx,ts,tsx}—— Gatsby 的组件和页面都在src/下，不是pages/或components/ - 若用了 Tailblocks，加一行
./src/components/tailblocks/**/*.js（注意路径前缀是src/，不是components/） - 别写
./pages/**/*.{js,ts,jsx,tsx}—— Gatsby v4+ 默认不用pages/目录结构，写了也白扫
如何让 darkMode: 'class' 真正生效
Gatsby 不会自动注入 dark 类到 标签，Tailwind 的 dark: 前缀就只是摆设。必须手动控制：
- 在
gatsby-browser.js里监听系统偏好并写入 class：exports.onInitialClientRender = () => {<br> if (window.matchMedia('(prefers-color-scheme: dark)').matches) {<br> document.documentElement.classList.add('dark')<br> }<br>} - 在用户点击切换按钮时，用
document.documentElement.classList.toggle('dark')，不要操作body或自定义 wrapper 元素 - 避免在
useEffect里做这事——Gatsby 的 SSR 阶段没window，会导致 hydration mismatch 报错
这个 class 必须直接落在 上，否则 dark:bg-gray-900 这类规则无法穿透到子元素。
CSS Modules 与 Tailwind 共存时最易踩的坑
很多人把 Tailwind 类直接写进 Button.module.css，结果发现样式不生效或哈希类名污染 HTML：
- 别在
.module.css里写@tailwind指令——它会被当成普通 CSS 解析，报错或静默失败 - Tailwind 类应全部写在 JSX 的
className属性里，例如className="p-3 bg-blue-500 hover:bg-blue-600" - 如果想复用
text-lg这类语义类，用@apply提取到自定义类里，再导入模块：.button { @apply p-3 bg-blue-500 text-white; }→ 然后import styles from './Button.module.css'→className={styles.button} - 千万别混用：比如
className={`${styles.button} p-4`}—— 这会让 PurgeCSS 误判p-4是未使用类而删除
真正难调试的点在于：PurgeCSS 的扫描是静态的，它只看字符串字面量，不执行 JS 拼接逻辑。任何动态生成的 Tailwind 类名都会消失。
