Hugo静态网站部署到GitLab Pages完整指南

前言

Hugo作为一款流行的静态网站生成器，与GitLab Pages的结合可以为我们提供免费的网站托管服务。本文将详细介绍如何将Hugo网站部署到GitLab Pages平台，从基础配置到高级优化一应俱全。

准备工作

在开始部署前，请确保您已完成以下准备工作：

1. 已安装Git版本控制系统并熟悉基本操作
2. 已完成Hugo网站的本地开发
3. 拥有GitLab账户
4. 了解基本的命令行操作

基础配置

设置正确的BaseURL

在Hugo的配置文件(config.toml或config.yaml)中，必须正确设置baseURL参数。这个URL应该与您的GitLab Pages地址匹配，格式通常为：

https://<您的用户名>.gitlab.io/<项目名称>/

如果您计划使用自定义域名，则baseURL应设置为您的自定义域名。

配置GitLab CI/CD

GitLab使用CI/CD管道来自动化构建和部署过程。我们需要在项目根目录下创建.gitlab-ci.yml文件来定义构建流程。

完整的CI/CD配置

以下是一个优化的.gitlab-ci.yml配置示例，它包含了：

1. 安装必要的构建工具
2. 安装Hugo扩展版(支持Sass/SCSS)
3. 安装Node.js环境
4. 执行Hugo构建
5. 对静态资源进行压缩优化

variables:
  DART_SASS_VERSION: 1.87.0
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  HUGO_VERSION: 0.146.7
  NODE_VERSION: 22.x
  TZ: Asia/Shanghai  # 根据您的时区设置

image:
  name: golang:1.24.2-bookworm

pages:
  script:
    # 安装brotli压缩工具
    - apt-get update
    - apt-get install -y brotli
    
    # 安装Dart Sass编译器
    - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - cp -r dart-sass/ /usr/local/bin
    - rm -rf dart-sass*
    - export PATH=/usr/local/bin/dart-sass:$PATH
    
    # 安装Hugo扩展版
    - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    
    # 安装Node.js环境
    - curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
    - apt-get install -y nodejs
    
    # 安装Node.js依赖(如果有)
    - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
    
    # 配置Git
    - git config core.quotepath false
    
    # 执行Hugo构建
    - hugo --gc --minify --baseURL ${CI_PAGES_URL}
    
    # 压缩静态资源
    - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec brotli -f -k {} \;
  
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

项目上传与部署

初始化Git仓库

在您的Hugo项目根目录下执行以下命令：

# 初始化Git仓库
git init

# 忽略public目录(构建产物不需要版本控制)
echo "/public" >> .gitignore

# 添加所有文件并提交
git add .
git commit -m "Initial commit"

# 添加远程仓库并推送
git remote add origin 您的GitLab仓库地址
git push -u origin master

构建过程监控

推送代码后，GitLab会自动触发CI/CD管道。您可以在项目的CI/CD页面查看构建进度和日志。构建成功后，您的网站将自动部署到GitLab Pages。

访问您的网站

构建成功后，您的网站将可以通过以下URL访问：

https://<您的用户名>.gitlab.io/<项目名称>/

高级配置

自定义域名

如果您想使用自己的域名：

1. 在项目设置中找到Pages设置
2. 添加您的自定义域名
3. 按照提示配置DNS解析

性能优化建议

1. 启用HTTP/2：GitLab Pages默认支持HTTP/2
2. 资源压缩：CI配置中已包含gzip和brotli压缩
3. 缓存策略：考虑为静态资源设置适当的缓存头

常见问题解决

1. 构建失败：检查CI日志，常见问题包括依赖缺失或配置错误
2. 样式丢失：确保使用了Hugo扩展版以支持Sass/SCSS
3. 页面404：检查baseURL配置是否正确

总结

通过本文的指导，您应该已经成功将Hugo网站部署到GitLab Pages。这种部署方式不仅免费，而且自动化程度高，每次代码推送都会触发自动构建和部署，非常适合个人博客或项目文档网站。