必须在基础模板（如base.html）的<head>中统一引入所有页面共用CSS，子模板禁止重复引入；href须用根相对路径（如/static/css/base.css），并按vars→base→utils→page顺序加载以保障层叠优先级。
模板引擎里必须写在基础布局中，不能分散在子模板里
所有页面共用的 CSS，只应在 base.html、layout.ejs 或 base.thymeleaf 这类基础模板的 <head> 区域统一引入。子模板（如 home.html、profile.html）禁止再单独加 <link> 引公共样式——否则会出现重复加载、顺序错乱、调试时找不到样式来源等问题。
常见错误现象：base.html 引了 common.css，profile.html 又自己加了一次 <link href="common.css">，结果 DevTools 里看到两条相同请求，且后加载的覆盖了前者的自定义属性声明。
- 确保所有子模板都通过
{% extends "base.html" %}或<th:block th:replace="~{base :: content}">等机制继承基础布局 - 基础模板中
<link>的href必须用根相对路径（如/static/css/base.css），避免因子模板所在目录层级不同导致 404 - 如果使用 Django，必须用
{% static 'css/base.css' %}，硬写href="css/base.css"在生产环境必然失效
引入顺序必须是 vars → base → utils → page
CSS 层叠优先级靠后加载的样式赢，但靠蛮力加 !important 不是解法。真正可控的方式是按语义分层、严格控制 <link> 出现顺序：
-
<link href="/static/css/vars.css">：仅含:root声明的 CSS 自定义属性（--color-primary、--space-md），供后续所有层引用 -
<link href="/static/css/base.css">：重置（normalize）、基础排版（h1、p）、容器类（.container），无业务语义 -
<link href="/static/css/utils.css">：原子工具类（.mt-4、.text-center），单属性、零嵌套 -
<link href="/static/css/page-profile.css">：最后加载，只作用于当前页面，可安全覆盖前面任意规则
如果顺序颠倒（比如把 page-profile.css 放最前），你会发现 .button 的背景色怎么也改不掉——它被后面加载的 utils.css 里一条泛匹配 [class*="btn"] 覆盖了。
立即学习“前端免费学习笔记（深入）”；
Django / Flask / Spring Boot 各自的静态路径陷阱
服务端模板不是纯前端，静态资源路径由后端框架解析，硬写相对路径大概率出错。
Django 必须用 {% load static %} + {% static 'css/base.css' %}，且 settings.py 中 STATICFILES_DIRS 指向正确目录；Flask 需确认 url_for('static', filename='css/base.css') 返回的是有效 URL；Spring Boot Thymeleaf 则依赖 spring.web.resources.static-locations 配置是否包含 classpath:/static/。
- 开发阶段浏览器 Network 面板里看到
404 /css/base.css？先检查后端是否真把该文件放在可访问路径下，而不是只放进了源码目录 - 上线后样式没更新？不是缓存问题，而是构建产物没复制进
static/目录，或 Nginx 没配置对/static/的 location 转发 - 禁止在模板里写
href="../css/base.css"或href="css/base.css"—— 这种路径在多级路由（如/admin/users/edit）下会直接 404
@import 在服务端模板中完全不该出现
哪怕你用的是 Sass 编译后的 CSS 文件，最终输出到 HTML 的 <link> 所指向的 CSS 文件里，也绝不能含有 @import 语句。它在服务端模板场景下只有坏处：
- 浏览器要先下载主 CSS，解析到
@import "common.css"再发起第二次请求，白屏时间拉长 - FOUC（Flash of Unstyled Content）风险极高，尤其在弱网下
- Webpack/Vite 构建时能处理
@import，但那是编译期行为；服务端模板渲染的是运行时 HTML，此时已无构建上下文
如果你看到某个 page.css 开头写着 @import "/static/css/base.css"，立刻删掉，把引入逻辑上提到模板层，用 <link> 显式管理。
真正难处理的从来不是“怎么引”，而是当多个团队共用一套模板系统时，有人偷偷在子模板里加 <style> 块覆盖全局按钮颜色，又不提 PR——这种隐性耦合比路径写错更难排查。
