GitLab Pages目录访问失效问题求助

一、先排查基础问题 #

1. 核对URL结构
   如果是项目级Pages，完整URL应该是 https://<用户名>.gitlab.io/<项目名>/<路径>，别漏了项目名！比如你可能得访问 exmpl.co/my-project/[branch]/ 而不是直接 exmpl.co/[branch]/。只有仓库名叫<用户名>.gitlab.io的用户级Pages，才能直接用根域名访问。

2. 检查web目录里有没有index.html
   你的CI脚本是把web/*复制到分支/提交目录，如果web里没index.html，访问目录路径（比如xxx/branch/）肯定404，就算有其他文件也得指定具体文件名。先确认web目录里有默认入口文件。

3. 看CI日志有没有复制失败
   去项目的CI/CD流水线日志里，查cp web/*那几步有没有报错——比如web目录不存在，或者没权限，导致根本没把文件复制到目标目录。要是web是空的或者不存在，分支/提交目录里啥都没有，自然404。

二、修复增量部署的核心问题 #

你参考的增量部署方案，关键是要保留之前部署的所有内容，但你现在的CI脚本每次都会重新建public目录，直接覆盖之前的所有文件。要实现增量，得用GitLab的缓存来保存之前的public目录：

修改后的CI配置 #

image: busybox
pages:
  script:
    # 先把缓存里的旧public目录恢复过来（如果有的话）
    - if [ -d "$CI_PROJECT_DIR/public_cache" ]; then cp -r "$CI_PROJECT_DIR/public_cache/" public/; fi
    # 创建当前分支和提交的目录，复制文件
    - mkdir -p "public/$CI_COMMIT_REF_NAME" "public/$CI_COMMIT_SHORT_SHA"
    # 用cp -r确保连子目录一起复制，避免漏文件；加个容错，防止web空目录导致流水线失败
    - cp -r web/* "public/$CI_COMMIT_REF_NAME/" || echo "web目录没文件，跳过复制"
    - cp -r web/* "public/$CI_COMMIT_SHORT_SHA/" || echo "web目录没文件，跳过复制"
    - cp test.html public/
    # 把当前的public目录备份到缓存里，下次用
    - cp -r public/ "$CI_PROJECT_DIR/public_cache/"
  artifacts:
    paths:
      - public
  cache:
    paths:
      - public_cache/
    # 设个缓存key，让所有分支共享同一个缓存（要隔离分支的话可以调整key）
    key: pages-public-cache

配置说明 #

• 用cache存之前的public内容，每次流水线先把缓存里的文件恢复到当前public，再添新的分支/提交内容
• 把cp web/*改成cp -r web/*，这样能复制web目录下的所有内容（包括子目录），避免漏文件
• 加|| echo ...是为了防止web目录为空时，复制命令报错导致流水线失败

三、其他排查点 #

• 查Pages部署状态：去项目的Settings > Pages页面，确认最新流水线已经部署成功，显示的域名和你访问的一致
• 清浏览器缓存：有时候浏览器缓存了旧的404页面，按Ctrl+F5强制刷新再试试
• 检查文件权限：可以在CI脚本里加chmod -R 755 public/，确保所有文件和目录都有可读权限，防止因权限问题返回404

内容的提问来源于stack exchange，提问作者Freddybobjo