GitLab Fork的Jekyll项目Pages异常：样式错乱、文章页报404

问题核心诱因 #

两类异常属于同源问题，均为Jekyll的baseurl配置与GitLab Pages实际部署路径不匹配导致：

• CSS样式加载异常：页面引用静态资源时未携带正确的路径前缀，浏览器向域名根目录请求CSS/JS等资源，资源不存在导致样式渲染失败
• 文章链接返回404：Jekyll生成的文章永久链接未拼接正确的子路径前缀，跳转时请求了站点下不存在的地址

通过模板创建的项目默认baseurl适配官方模板仓库路径，解除Fork关系后若仓库名与官方模板不一致、未同步修改配置，就会触发该问题。

修复步骤 #

• 确认站点部署路径
  若使用GitLab默认分配的Pages域名，普通项目的访问路径前缀为/你的项目仓库名；若仓库名与GitLab账号名完全一致、为根Pages仓库（即仓库名为账号名.gitlab.io），则无路径前缀；若绑定了自定义域名，同样无路径前缀。
• 修改Jekyll核心配置
  打开项目根目录下的_config.yml文件，找到baseurl配置项，按实际路径修改：

  普通项目示例：仓库名为my-tech-blog时，配置为baseurl: "/my-tech-blog"
  根Pages仓库/绑定自定义域名场景：配置为baseurl: ""
  注意：普通项目配置baseurl时，路径开头必须带斜杠、结尾不要加斜杠，否则会出现路径拼接错误

• 校验全站资源与链接写法
  检查所有页面的资源引用、内链跳转，不要硬编码根路径，必须拼接baseurl变量：
  • HTML场景下引用静态资源：统一使用{{ site.baseurl }}/资源相对路径格式，例如样式表引用写为<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/main.css">
  • Markdown场景下写内链：统一使用[链接文本]({{ site.baseurl }}/文章相对路径)格式
    官方模板默认已适配该写法，若之前手动修改路径时删除了baseurl拼接，需要恢复。
• 校验CI构建配置
  打开项目根目录下的.gitlab-ci.yml文件，确认构建脚本没有硬编码错误的baseurl覆盖参数，标准构建配置参考：

  pages:
    stage: deploy
    script:
      - gem install bundler
      - bundle install
      - bundle exec jekyll build -d public
    artifacts:
      paths:
        - public
  only:
    - main
  

  如果构建命令里手动加了--baseurl参数，请删除避免配置冲突。
• 重新部署验证
  将所有修改提交推送到仓库的默认分支，等待CI流水线执行完成后，按Ctrl+F5强制刷新浏览器缓存清除旧资源，再访问站点验证功能即可。

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