一、当你的网站“消失”了：认识GitLab Pages与404错误
想象一下，你刚刚完成了一个漂亮的个人博客或者项目介绍页面，满怀期待地通过GitLab Pages部署到了网上。你兴奋地把链接分享给朋友，结果对方却回复你：“兄弟，你的网站打不开，显示404 Not Found。”
这感觉就像精心准备的派对，客人到了却发现大门紧闭。别慌，这个“404”是静态网站部署中非常常见的“拦路虎”，尤其是在GitLab Pages这样的平台上。简单来说，GitLab Pages是GitLab提供的一个免费功能，它能自动将你仓库里的代码（比如HTML、CSS、JavaScript文件）构建并发布成一个可以通过特定网址访问的网站。而404错误，就是服务器（在这里是GitLab的服务器）告诉你：“你访问的这个网页地址，我这儿没有。”
接下来，我们就化身“网站侦探”，一步步排查那些导致你的GitLab Pages网站“消失”的常见原因。
二、案件现场勘查：从项目结构开始查起
第一个也是最常见的案发现场，就是你的项目仓库结构。GitLab Pages在构建时，会从一个默认的目录（通常是public目录，或者你指定的输出目录）里寻找网站文件。如果入口文件放错了地方，自然就会导致404。
技术栈：纯静态网站 (HTML/CSS/JS)
假设你的项目结构是这样的：
我的博客项目/
├── .gitlab-ci.yml # GitLab的自动化构建配置文件
├── src/ # 你的源代码目录
│ ├── css/
│ │ └── style.css
│ ├── js/
│ │ └── app.js
│ └── index.html # 你的网站首页源代码
└── README.md
你直接这样部署，百分百会404。因为GitLab Pages默认会去项目的根目录找index.html，但你的index.html却在src/文件夹里。
正确的做法是，你需要通过构建脚本，将最终生成的网站文件（即浏览器能直接运行的文件）放到一个特定的目录。这个信息需要在.gitlab-ci.yml文件中明确告诉GitLab。
让我们看一个完整的.gitlab-ci.yml示例，它清晰地定义了构建和发布的流程：
# 技术栈：纯静态网站 (HTML/CSS/JS)
# 定义整个Pages的构建流程
pages: # 这个job名字必须是‘pages’，这是GitLab的约定
stage: deploy
script:
# 假设我们不需要复杂的构建，只是把文件复制到公共目录
# 如果你的项目用了Vue/React等框架，这里会是 `npm run build`
- echo '开始构建静态网站...'
- mkdir -p public # 创建一个名为‘public’的目录，这是GitLab Pages默认的发布目录
- cp -r src/* public/ # 将src目录下的所有文件复制到public目录
# 现在，public目录下就有了 index.html, css/, js/ 等
artifacts:
paths:
- public # 告诉GitLab，将public目录保留下来，用于发布
only:
- main # 只有推送到main分支时，才触发这个Pages部署
在这个例子中，script部分的命令是关键。它创建了public文件夹，并把src里的内容复制进去。这样，GitLab的服务器最终看到的就是一个包含index.html的public目录，网站就能正常打开了。
三、深入线索分析：配置文件与访问路径的玄机
如果结构没问题，但网站的部分页面（比如about.html）或者资源（如图片、CSS文件）仍然404，那就要检查更细微的线索了。
线索一：.gitlab-ci.yml配置错误
上面的示例是基础版。如果你使用了像Hugo、Jekyll、VuePress这样的静态网站生成器，配置会稍有不同。你必须确保artifacts:paths指向的是生成器输出的目录，而不是源代码目录。
例如，对于Hugo，其默认输出目录是public，但它是自己生成的：
pages:
stage: deploy
image: registry.gitlab.com/pages/hugo:latest # 使用包含Hugo的Docker镜像
script:
- hugo # 运行hugo命令，它会自动生成网站到`public`目录
artifacts:
paths:
- public # 正确：指向Hugo生成的目录
only:
- main
如果你错误地指向了content或layouts这些源码目录，就会导致404。
线索二：相对路径与绝对路径的陷阱
这是前端开发中一个经典问题。假设你的网站最终访问地址是https://username.gitlab.io/my-project/，而你的页面里引用了一个CSS文件：
<!-- 在 index.html 中 -->
<!-- 错误的相对路径写法（如果你的站点不在根目录） -->
<link rel="stylesheet" href="css/style.css">
<!-- 当访问 https://username.gitlab.io/my-project/ 时，
浏览器会尝试加载 https://username.gitlab.io/my-project/css/style.css，这是正确的。
但如果你的链接是跳转到 /about，然后about页面也用‘css/style.css’，就会变成从 /about 目录下去找，导致404。
-->
<!-- 推荐的根目录相对路径写法 -->
<link rel="stylesheet" href="/my-project/css/style.css">
<!-- 以‘/’开头，表示始终从网站的域名根目录开始解析，路径更稳定。 -->
在GitLab Pages中，如果你的项目名是my-project，那么你的网站根URL就是/my-project/。使用根目录相对路径（以/开头）能有效避免因页面层级变化导致的资源加载失败。当然，最一劳永逸的方法是在构建时配置基础路径（Base URL），静态网站生成器通常都支持这个选项。
四、追踪隐藏的元凶：缓存、分支与权限
有些时候，问题不在你的代码，而在环境。
元凶一：浏览器和GitLab的缓存 你明明已经修复了问题并重新推送了代码，但访问网站还是旧的错误页面。这时，请先尝试：
- 浏览器硬刷新：按
Ctrl + F5(Windows) 或Cmd + Shift + R(Mac)。 - 清除GitLab Runner缓存：在
.gitlab-ci.yml中，你可以选择性地缓存一些依赖以加速构建，但有时陈旧的缓存会导致构建结果异常。你可以尝试暂时注释掉cache配置，或者手动在GitLab项目设置中清除Runner缓存。 - 等待GitLab Pages同步：GitLab Pages的更新不是瞬时的，可能会有几分钟的延迟。你可以去项目的
Settings > Pages页面，查看最新的发布状态和链接。
元凶二：部署的分支或目录不对
回顾一下我们示例中.gitlab-ci.yml的最后一部分：
only:
- main
这表示只有推送到main分支的代码才会触发Pages部署。如果你一直在dev或feature分支上修改，然后去访问Pages，看到的自然是上一次main分支部署的内容，可能就会404。确保你部署的是正确的分支。
元凶三：项目权限是私有的 GitLab Pages默认只为公开（Public）项目提供公开访问。如果你的项目是私有（Private）或内部（Internal）的，你需要：
- 登录GitLab账户才能访问你的Pages网站。
- 或者，在项目设置的
Settings > General > Visibility中，将Pages的可见性单独设置为Everyone（如果项目是Internal或Private）。
五、终极破案工具：使用CI/CD流水线日志
当以上方法都试过后问题依旧，你的终极武器就是GitLab CI/CD流水线日志。这是破案的“黑匣子”。
- 进入你的GitLab项目，点击侧边栏的
CI/CD > Pipelines。 - 找到最近一次Pages部署对应的流水线，点击进去。
- 点击
pages这个job，查看详细的日志。
日志会告诉你：
- 构建是否成功（有没有红色错误信息）。
script里的每一条命令是否按预期执行（比如，是否成功创建了public目录？hugo命令是否报错？）。- 最后，
Uploading artifacts...部分会显示它把哪些文件上传到了Pages服务器。仔细核对这里列出的文件路径，是否包含你的index.html。如果这里没有，那网站必然404。
通过日志，你可以精准定位到是命令执行出错，还是最终产物不符合预期。
应用场景、技术优缺点、注意事项与总结
应用场景：GitLab Pages非常适合部署个人技术博客、项目文档、作品集、小型宣传页面等任何静态内容。它无缝集成在GitLab的代码仓库中，实现了“代码即文档，提交即部署”的DevOps理念。
技术优缺点：
- 优点：完全免费（有一定限额）、与GitLab CI/CD深度集成、支持自定义域名和SSL证书、无需自己维护服务器。
- 缺点：功能相对单一，仅适用于静态资源；构建环境和时长有限制；访问速度可能受地理位置影响。
注意事项：
- 仔细阅读官方文档：不同静态网站生成器在GitLab Pages上的配置可能有细微差别。
- 关注配额限制：免费的GitLab.com账户有月度CI/CD时长和Pages带宽限制，对于个人小站通常足够。
- 自定义域名需配置DNS：如果需要使用自己的域名，别忘了配置CNAME或A记录。
- 安全考虑：不要将敏感信息（如API密钥）硬编码在将被发布的静态文件中。
文章总结：
排查GitLab Pages的404错误，是一个系统性的调试过程。我们需要像一个侦探一样，从最明显的“现场”（项目结构）开始，检查“作案工具”（.gitlab-ci.yml配置）是否使用得当，分析“行动路线”（文件引用路径）是否存在偏差，并考虑“环境因素”（缓存、分支、权限）的干扰。最后，善于利用“监控记录”（CI/CD日志）来还原事件全过程，找到根本原因。掌握这套排查方法，你就能从容应对Pages部署中的各种“小意外”，让你的网站稳定地运行在互联网上。
评论