TailwindCSS 路线 01：从 0 到可交付的工程化工作流

这一篇是“真正上手”的起点：把 TailwindCSS 安装好、接入构建管道、确认样式生效，然后给你一套可长期维护的落地方式（Token/暗色/组件写法）。

你正在看的这个仓库已经是 Next.js + Tailwind v4 的落地形态。你可以对照本文的“检查清单”，快速判断你的项目有没有接对。

01 TailwindCSS 到底是什么（用一句话说清）#

TailwindCSS 是一套 utility-first（工具类优先）的 CSS 框架：

• 你不是写一堆自定义 class 再去写 CSS 文件
• 你直接在组件上写类名组合出 UI

它的核心收益不是“少写几行 CSS”，而是让团队的间距/字体/颜色/交互反馈更容易统一，且更不容易漂。

02 安装：以 Next.js + Tailwind v4 为例（从 0 到跑起来）#

如果你是新项目：

1. 创建 Next.js（App Router）

npx create-next-app@latest my-app
cd my-app

2. 安装 Tailwind v4（以及 PostCSS 插件）

npm i tailwindcss @tailwindcss/postcss

3. 配置 PostCSS（postcss.config.mjs）

const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
export default config;

4. 全局样式入口（src/app/globals.css）

@import "tailwindcss";

5. 启动开发服务器并验证

npm run dev

验证方式：随便找个组件加上 className="text-red-500"，页面文字应该立刻变红。

这个仓库里你可以直接对照：根目录的 postcss.config.mjs、package.json、以及 src/app/globals.css。

03 常见“装了但不生效”的排错清单#

如果你写了 class 但页面没变化，通常是这几类问题：

• 全局 CSS 没有被引入：Next.js App Router 需要在 src/app/layout.tsx 引入 globals.css
• PostCSS 插件没生效：postcss.config.mjs 没配置 @tailwindcss/postcss
• 样式被覆盖：你在别的 CSS 里写了更高优先级（例如全局 * { color: ... }）
• 你以为改了 class 但其实没刷新：热更新异常时重启 dev server

04 第一天就该学会的 6 个用法（有例子）#

A. 布局：Flex / Grid#

<div class="flex items-center justify-between gap-4">
  <div class="min-w-0">左侧</div>
  <button class="shrink-0">按钮</button>
</div>

B. 间距：padding / margin / space-*#

• 外层用 px-4 py-3
• 列表用 space-y-2 比每项写 mt 更整齐

C. 字体与排版：text-* / font-* / leading-*#

<h1 class="text-3xl font-bold tracking-tight">标题</h1>
<p class="mt-2 text-sm leading-relaxed text-stone-600">说明</p>

D. 交互反馈：hover / active / focus-visible#

<a class="rounded-xl px-3 py-2 transition-colors hover:bg-stone-100 focus-visible:outline-none focus-visible:ring-4">
  可点击
</a>

E. 响应式：sm / md / lg（少用、用得有语义）#

<div class="grid gap-4 md:grid-cols-2">
  <div>左</div>
  <div>右</div>
</div>

F. 暗色模式：优先用 Token（变量），少量用 dark:#

你不想每个组件写一套 dark: 分支。更推荐：

1. 用 CSS 变量承载主题
2. 组件消费变量（bg-[var(--surface)]）

05 把“设计 Token”固定下来（这是可维护的关键）#

建议你从 4 个变量开始（够用且不复杂）：

• --background：页面背景
• --surface：卡片/浮层背景
• --border：边框/分割线
• --accent：强调色（链接、主按钮、选中态）

放在 globals.css 的 :root 与 .dark 中。这样：

• 主题切换只改变量值
• 组件不需要写两套颜色

06 组件写法：从“能交付”到“可维护”的抽象顺序#

建议顺序（非常实用）：

1. 先把 UI 写对（class 可以长）
2. 重复出现的组合样式 → 抽成常量字符串（仍在同文件）
3. 复用变多 → 抽成公共组件（Button / Badge / Card）
4. 最后再做变体系统（variant/size），不要一开始就追求“优雅”

07 本篇小结#

你需要的不是“背类名”，而是一套能持续交付的样式基建：

• 安装接入正确（入口/插件/全局 CSS）
• 第一天掌握核心用法（布局/间距/排版/交互/响应式/暗色）
• 以 Token + 变量为中心做主题与统一风格

下一篇开始讲布局与响应式，但会以“团队规范/模板”的方式讲，避免把断点写成一团。