HTML / CSS / 系统课时
配置源码扫描范围
配置源码扫描范围
Tailwind 只有在扫描到完整工具类名称后,才会生成对应 CSS。本课使用 Tailwind CSS v4 的源码检测方式,明确主源码目录、额外组件目录和排除目录,并通过构建结果验证配置是否真正生效。
学习目标
- 理解源码扫描范围与最终 CSS 之间的关系。
- 使用
source()、@source和@source not控制检测路径。 - 通过可重复的命令确认类名被包含或排除。
扫描范围为什么重要
Tailwind 会把模板和组件文件当作纯文本查找候选类名,再为识别到的完整类名生成样式。扫描目录漏配时,页面虽然写了 bg-sky-600,输出 CSS 中却没有该规则;扫描范围过大时,则会增加无效检测与维护成本。

源码中的类名应保持完整、静态可见。不要拼接 bg-${color}-600 这类字符串,因为扫描器不会执行 JavaScript;应把可选值映射为 bg-blue-600、bg-red-600 等完整字符串。
配置显式来源
假设样式入口位于 src/input.css,业务页面在 src,共享组件在 packages/ui,旧代码在 src/legacy。可以把自动检测基准限制到当前目录,再额外注册共享目录并排除旧目录。
@import "tailwindcss" source(".");
@source "../packages/ui";
@source not "./legacy";source(".") 让自动检测从样式文件所在的 src 目录开始;@source 补充默认不会纳入的共享组件;@source not 则明确忽略旧目录。路径按样式文件位置解析,移动 input.css 后要同步检查相对路径。
如果项目仍使用 Tailwind CSS v3,应在 tailwind.config.js 的 content 字段配置模板路径,不要把 v3 的 JavaScript 配置与本课的 v4 CSS 指令混用。
构建并验证
在共享组件中加入 bg-sky-600,在旧目录中加入 bg-red-500,然后执行构建与断言。以下命令假设项目已经安装 tailwindcss 和 @tailwindcss/cli。
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css
if grep -q '\.bg-sky-600' ./dist/output.css && ! grep -q '\.bg-red-500' ./dist/output.css; then
echo "扫描范围配置正确"
else
echo "扫描范围需要检查"
fi预期输出
扫描范围配置正确如果结果失败,先确认示例类名确实以完整字符串写入对应文件,再检查相对路径、.gitignore、node_modules 和构建命令的工作目录。修改配置后应重新生成 CSS,不能只刷新浏览器。
常见失效原因
最常见的问题是路径相对基准理解错误、类名通过字符串拼接产生,以及组件实际存放在默认忽略目录中。排查时应按“源文件存在完整类名 → 路径被扫描 → 输出 CSS 包含选择器 → 页面正确加载 CSS”的顺序逐层验证。