游乐游手机版
首页/前端开发/文章详情

Next.js14项目如何引入Tailwind CSS并开启按需生成

时间:2026-08-23 14:35
是,Next js 14 已将 App Router 作为默认架构,传统的 Pages Router 已进入维护阶段;其核心能力包括 Server Components、Layouts、Streaming、Server Actions 以及 Edge 运行时优化。确认 Next js 14 是否已启

是,Next.js 14 已将 App Router 作为默认架构,传统的 Pages Router 已进入维护阶段;其核心能力包括 Server Components、Layouts、Streaming、Server Actions 以及 Edge 运行时优化。

如何在Next.js14项目里引入Tailwind CSS并开启按需生成?

确认 Next.js 14 是否已启用 App Router

在 Next.js 14 中,App Router 已成为默认且推荐的方案。不过,Tailwind CSS 的按需生成机制(也就是扫描 content 路径来提取 class)在 App Router 与 Pages Router 下的配置方式略有差异。如果你的项目是通过 create-next-app 创建,且没有手动切回旧架构,那么大多数情况下就是 App Router。这也意味着,你的 tailwind.config.js 中 content 配置必须包含 app/**/*.{js,ts,jsx,tsx}。

你可以先检查项目根目录中是否存在 app/layout.tsx 或 app/page.tsx;如果存在,基本可以确认项目使用的是 App Router。若没有,则可能仍在使用 Pages Router,这时要特别确认 pages/**/*.{js,ts,jsx,tsx} 是否已经加入扫描路径。

  • App Router 项目必须在 content 中明确加入 app/**/*.{js,ts,jsx,tsx},否则组件里写的 class 无法被 Tailwind 识别,最终表现为样式失效
  • Pages Router 也是同样的逻辑,需要补上 pages/**/*.{js,ts,jsx,tsx},遗漏后就等于没有正确开启按需生成
  • 如果项目同时使用了 app 和 pages 两套目录结构,那么两个路径都必须完整配置,否则部分页面或组件中的 class 会被漏扫

配置 tailwind.config.js 开启真正按需生成

Tailwind CSS 默认就支持按需生成,但这个“按需”是否生效,完全取决于 content 配置是否准确。它不会自动扫描项目中所有 JS/TS 文件,而只会处理你手动声明的 glob 路径。很多开发者在 Next.js 14 项目里配置完 Tailwind 后发现类名不生效,问题通常不是 Tailwind 出错,而是 content 少了目录、扩展名或文件类型。

一个常见且适用于 App Router 的 tailwind.config.js 配置通常如下:

/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
"./app/**/*.{js,ts,jsx,tsx}",
"./components/**/*.{js,ts,jsx,tsx}",
"./layouts/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {},
},
plugins: [],
}
  • ./app/**/*.{js,ts,jsx,tsx} 是 App Router 项目的关键配置项,前面的 ./ 不建议省略,否则在某些构建环境下可能无法正确匹配
  • 像 components 这样的自定义组件目录也要手动加入,因为 Tailwind 不会自动判断你的 UI 组件存放位置
  • 不要使用类似 **/*.tsx 这种过于宽泛的写法,Next.js 构建过程中可能因为性能优化而导致扫描不稳定,反而增加漏扫风险
  • 如果项目中使用了 MDX,例如 app/blog/[slug]/page.mdx,还需要补充 ./app/**/*.{mdx},否则 MDX 文件里的 class 不会被打包进最终 CSS

验证按需生成是否真生效

想确认 Tailwind CSS 按需生成是否真正启用,最直观的方法是在某个 app/page.tsx 文件中临时加入一个不常见的 class,例如 bg-[#1a2b3c] 或 text-7xl(默认主题中未必定义了 7xl),然后观察浏览器页面是否正确渲染。如果没有效果,就说明按需生成链路没有打通——最常见的原因仍然是 content 没有覆盖该文件,或者扩展名未配置完整。

  • 执行 npm run dev 后,打开浏览器开发者工具,查找生成的