Back to Details

tailwindcss-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tailwind CSS Debugging & Troubleshooting

Tailwind CSS 调试与故障排除

Common Issues & Solutions

常见问题与解决方案

1. Styles Not Applying

1. 样式未生效

Check Content Detection

检查内容检测

v4 automatically detects content, but if styles are missing:
css
/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";
v4会自动检测内容，但如果样式缺失：
css
/* 显式指定资源路径 */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";

Verify Class Names

验证类名

html
<!-- WRONG - Dynamic class won't be detected -->
<div class={`text-${color}-500`}>

<!-- CORRECT - Use complete class names -->
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>
html
<!-- 错误写法 - 动态类名无法被检测 -->
<div class={`text-${color}-500`}>

<!-- 正确写法 - 使用完整类名 -->
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>

Check Build Process

检查构建流程

bash
undefined
bash
undefined

Restart dev server

重启开发服务器

npm run dev
npm run dev

Clear cache and rebuild

清除缓存并重新构建

rm -rf node_modules/.vite npm run build
undefined
rm -rf node_modules/.vite npm run build
undefined

2. v4 Migration Issues

2. v4迁移问题

PostCSS Plugin Changed

PostCSS插件变更

javascript
// OLD (v3)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// NEW (v4)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}
javascript
// 旧版（v3）
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// 新版（v4）
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

Configuration Moved to CSS

配置移至CSS文件

css
/* v4 - Configure in CSS, not JS */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}
css
/* v4 - 在CSS中配置，而非JS文件 */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}

Dark Mode Variant

深色模式变体

css
/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));
css
/* v4 - 如果使用选择器策略，需添加以下配置 */
@custom-variant dark (&:where(.dark, .dark *));

3. Classes Being Overridden

3. 类名被覆盖

Check Specificity

检查优先级

css
/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */
css
/* 浏览器开发者工具：检查元素 → 样式面板 */
/* 查找被划掉的样式规则 */

Solutions

解决方案

html
<!-- Use !important (last resort) -->
<div class="!mt-0">

<!-- Or increase specificity with variants -->
<div class="[&]:mt-0">
html
<!-- 使用!important（最后手段） -->
<div class="!mt-0">

<!-- 或者通过变体提高优先级 -->
<div class="[&]:mt-0">

Check Import Order

检查导入顺序

css
/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css";  /* After Tailwind */
css
/* 自定义CSS应在Tailwind之后导入 */
@import "tailwindcss";
@import "./custom.css";  /* 在Tailwind之后 */

4. Typography Plugin Issues

4. Typography插件问题

Styles Not Applied

样式未生效

css
/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";
css
/* 确保已加载插件 */
@plugin "@tailwindcss/typography";

Utilities Overridden by Prose

工具类被Prose覆盖

html
<!-- Use element modifiers -->
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">

<!-- Or escape prose entirely -->
<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>
html
<!-- 使用元素修饰符 -->
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">

<!-- 或者完全脱离Prose样式 -->
<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>

5. Forms Plugin Issues

5. Forms插件问题

Styles Not Applied to Plain Inputs

原生输入框样式未生效

html
<!-- Forms plugin only styles inputs with type attribute -->
<input type="text" />  <!-- ✓ Styled -->
<input />              <!-- ✗ Not styled -->
html
<!-- Forms插件仅为带有type属性的输入框添加样式 -->
<input type="text" />  <!-- ✓ 已添加样式 -->
<input />              <!-- ✗ 未添加样式 -->

Using Class Strategy

使用类策略

css
@plugin "@tailwindcss/forms" {
  strategy: class;
}
html
<!-- Now explicitly opt-in -->
<input type="text" class="form-input" />
css
@plugin "@tailwindcss/forms" {
  strategy: class;
}
html
<!-- 现在需要显式启用样式 -->
<input type="text" class="form-input" />

Debugging Tools

调试工具

VS Code Extension

VS Code扩展

bash
undefined
bash
undefined

Install Tailwind CSS IntelliSense

安装Tailwind CSS智能提示扩展

code --install-extension bradlc.vscode-tailwindcss

Features:
- Autocomplete for class names
- Hover previews showing CSS
- Linting for errors
- Color decorators
code --install-extension bradlc.vscode-tailwindcss

功能：
- 类名自动补全
- 悬停预览对应的CSS样式
- 错误代码检查
- 颜色装饰器

Debug Screens Plugin

Debug Screens插件

bash
npm install -D @tailwindcss/debug-screens
css
@plugin "@tailwindcss/debug-screens";
html
<!-- Shows current breakpoint in corner -->
<body class="debug-screens">
bash
npm install -D @tailwindcss/debug-screens
css
@plugin "@tailwindcss/debug-screens";
html
<!-- 页面角落会显示当前断点信息 -->
<body class="debug-screens">

Browser DevTools

浏览器开发者工具

  1. Inspect Element → See computed styles
  2. Styles Panel → See which rules apply
  3. Filter → Search for Tailwind classes
  4. Computed Tab → See final computed values
  1. 检查元素 → 查看计算后的样式
  2. 样式面板 → 查看生效的规则
  3. 筛选 → 搜索Tailwind类名
  4. 计算选项卡 → 查看最终计算值

Check Generated CSS

检查生成的CSS

bash
undefined
bash
undefined

Output CSS to file for inspection

将CSS输出到文件以便检查

npx tailwindcss -o output.css --content './src/**/*.{html,js}'
npx tailwindcss -o output.css --content './src/**/*.{html,js}'

With verbose logging

启用详细日志

DEBUG=tailwindcss:* npm run build
undefined
DEBUG=tailwindcss:* npm run build
undefined

v4 Specific Debugging

v4专属调试技巧

Check Plugin Loading

检查插件加载情况

bash
undefined
bash
undefined

Look for plugin-related errors

查找与插件相关的错误

npm run build 2>&1 | grep -i plugin
undefined
npm run build 2>&1 | grep -i plugin
undefined

Verify CSS Variable Output

验证CSS变量输出

css
/* In browser DevTools, check :root for variables */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}
css
/* 在浏览器开发者工具中，查看:root下的变量 */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}

Content Detection Issues

内容检测问题

css
/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* Exclude paths */
@source not "./src/generated/**";
css
/* 如果自动检测失败，添加显式资源路径 */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* 排除指定路径 */
@source not "./src/generated/**";

Common Error Messages

常见错误提示

"Cannot find module '@tailwindcss/postcss'"

"Cannot find module '@tailwindcss/postcss'"

bash
npm install -D @tailwindcss/postcss
bash
npm install -D @tailwindcss/postcss

"Unknown at-rule @theme"

"Unknown at-rule @theme"

Using v3 tooling with v4 syntax. Update your build setup:
bash
npm install -D tailwindcss@latest @tailwindcss/postcss@latest
使用了v3工具链搭配v4语法。请更新构建环境：
bash
npm install -D tailwindcss@latest @tailwindcss/postcss@latest

"Class 'X' doesn't exist"

"Class 'X' doesn't exist"

Dynamic class generation issue:
javascript
// BAD
const classes = `bg-${dynamic}-500`

// GOOD
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]
动态类名生成问题：
javascript
// 错误写法
const classes = `bg-${dynamic}-500`

// 正确写法
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]

"Styles not updating in development"

"Styles not updating in development"

bash
undefined
bash
undefined

Restart dev server

重启开发服务器

npm run dev
npm run dev

Clear Vite cache

清除Vite缓存

rm -rf node_modules/.vite
rm -rf node_modules/.vite

Clear Next.js cache

清除Next.js缓存

rm -rf .next
undefined
rm -rf .next
undefined

Performance Debugging

性能调试

Large CSS Output

生成的CSS文件过大

bash
undefined
bash
undefined

Check CSS file size

检查CSS文件大小

ls -lh dist/assets/*.css
ls -lh dist/assets/*.css

If too large, check for:

如果文件过大，排查以下问题：

1. Dynamic class generation

1. 动态类名生成

2. Unnecessary safelisting

2. 不必要的安全列表配置

3. Unused plugins

3. 未使用的插件

undefined
undefined

Slow Builds

构建速度缓慢

bash
undefined
bash
undefined

Time the build

统计构建耗时

time npm run build
time npm run build

v4 should be very fast

v4构建速度应该非常快

Full build: <1s

完整构建：<1秒

Incremental: microseconds

增量构建：微秒级

undefined
undefined

Debugging Checklist

调试检查清单

Initial Setup

初始设置

  • Correct import: 
    @import "tailwindcss";
  • PostCSS plugin: 
    @tailwindcss/postcss
    (not 
    tailwindcss
    )
  • Vite plugin: 
    @tailwindcss/vite
    (if using Vite)
  • CSS file imported in entry point
  • Development server restarted after changes
  • 正确导入：
    @import "tailwindcss";
  • PostCSS插件：
    @tailwindcss/postcss
    （而非
    tailwindcss
    ）
  • Vite插件：
    @tailwindcss/vite
    （如果使用Vite）
  • 入口文件中已导入CSS文件
  • 修改配置后已重启开发服务器

Styles Not Applying

样式未生效

  • Class name is complete (no dynamic generation)
  • File is in content path
  • Browser cache cleared
  • No CSS specificity conflicts
  • Check DevTools for overridden styles
  • 类名是完整的（无动态生成）
  • 文件在内容检测路径内
  • 已清除浏览器缓存
  • 无CSS优先级冲突
  • 在开发者工具中检查是否有被覆盖的样式

After Migration

迁移后检查

  • tailwind.config.js removed or converted
  • @theme directive used for customization
  • PostCSS config updated
  • Dark mode variant added if using selector strategy
  • Plugins updated to v4-compatible versions
  • tailwind.config.js已移除或完成转换
  • 使用@theme指令进行自定义配置
  • PostCSS配置已更新
  • 如果使用选择器策略，已添加深色模式变体
  • 插件已更新至兼容v4的版本

Production Issues

生产环境问题

  • NODE_ENV=production
  • Build output includes styles
  • CSS file linked correctly
  • No dynamic class generation issues
  • NODE_ENV=production
  • 构建输出包含样式文件
  • CSS文件已正确链接
  • 无动态类名生成问题

Getting Help

获取帮助

Create Minimal Reproduction

创建最小复现示例

bash
undefined
bash
undefined

Create fresh project

创建新项目

npm create vite@latest repro -- --template react-ts cd repro npm install -D tailwindcss @tailwindcss/vite
npm create vite@latest repro -- --template react-ts cd repro npm install -D tailwindcss @tailwindcss/vite

Add minimal code that shows the issue

添加能复现问题的最简代码

Share on GitHub Issues or Discord

在GitHub Issues或Discord上分享

undefined
undefined

Resources

资源