GitLab Pages CSS 404主因是Linux服务器严格区分大小写，需确保HTML中href路径（如CSS/styles.css）与仓库实际文件名及目录大小写完全一致，并验证浏览器可直接访问该URL返回200。
GitLab Pages 的 CSS 文件 404：先确认服务器是否区分大小写
GitLab Pages 底层运行在 Linux 环境，文件系统严格区分大小写。这意味着 _variables.scss 和 _Variables.scss 是两个不同文件；如果 HTML 中 <link href="CSS/styles.css">，但实际文件是 css/styles.css（小写 css），就会 404。
这不是 GitLab 特有行为，而是所有类 Unix 服务器的默认规则 —— 和你在 Windows 或 macOS 本地开发时“不敏感”的体验完全不同。
- 在本地用 VS Code Live Server 能加载成功，不代表部署后能加载
- GitHub Pages 同样区分大小写，但部分用户误以为“不区分”，其实是本地 Git 配置或编辑器缓存掩盖了问题
- Git 自身在 Windows/macOS 默认开启
core.ignorecase true，导致你重命名CSS → css时，Git 可能根本没检测到变更
检查 <link> 中的 href 路径是否匹配实际部署结构
GitLab Pages 默认从项目根目录发布，但实际访问 URL 是 https://<username>.gitlab.io/<project-name>/。这时“网站根目录”对浏览器来说是 /<project-name>/，不是仓库根。
所以：href="CSS/styles.css" 实际请求的是 /<project-name>/CSS/styles.css，必须确保该路径下真有这个文件（注意大小写 + 目录名拼写）。
立即学习“前端免费学习笔记（深入）”；
- 直接在浏览器打开
https://<username>.gitlab.io/<project-name>/CSS/styles.css，看是否返回 CSS 内容（200）还是 404 - 打开 DevTools → Network → 切换到 CSS 过滤，点刷新，看具体哪个
href请求失败、状态码是多少、响应 preview 是否为空 - 避免混用路径风格：不要在 HTML 里用
./css/styles.css，在 SCSS 里又用@import '../assets/css/base'—— 容易因层级错位失效
SCSS 编译后 CSS 引用图片或字体时的路径陷阱
SCSS 中的 url() 是相对于最终生成的 CSS 文件位置解析的，不是相对于 SCSS 源文件。比如：
// _base.scss
background: url("../images/logo.png");
如果编译后 main.css 输出在 public/css/main.css，那它会去找 public/images/logo.png —— 不是 src/scss/images/，也不是 public/css/images/。
- 确认构建脚本（如
sassCLI 或 Webpack）输出 CSS 的目标路径，并按此反推url()中的相对路径 - 若使用根相对路径
url("/images/logo.png")，则必须保证public/images/在部署后位于 GitLab Pages 的站点根路径下（即能通过/<project-name>/images/logo.png访问） - CI/CD 构建阶段若清空
public/并只拷贝部分文件，可能漏掉images/目录 —— 检查.gitlab-ci.yml的artifacts或pagesjob 输出内容
修复已提交的大小写错误文件名
Git 在大小写不敏感系统（Windows/macOS）上无法原生识别 CSS → css 这类纯大小写变更。直接改名再 commit，Git 往往认为“没变化”或“删旧建新”，导致仓库里残留两个版本，CI 构建时行为不可控。
正确做法是强制 Git 重新注册文件名：
- 运行
git mv -f CSS css（注意加-f强制覆盖） - 或者分两步：
git mv CSS css_temp && git mv css_temp css - 提交前用
git status确认显示为 “renamed: CSS/styles.css → css/styles.css”，而不是 “deleted/added” - 推送后，在 GitLab 仓库页面直接点击
css/styles.css链接验证是否可访问
最容易被忽略的是：即使你本地改了文件名、CI 也成功构建，如果 Git 历史中仍存在大写的旧路径引用（比如旧版 HTML 或 CI 脚本里还写着 CSS/），它们不会自动更新 —— 必须手动搜索并替换所有硬编码路径。
