快速部署到现代托管平台

Hugo 的部署如同将精心制作的艺术品送上舞台，每种平台都有其独特的光彩。

将站点发布到线上只需少量步骤。可以直接上传生成的 public 目录到任意静态托管服务，或通过 Git 连接平台以便每次推送后自动构建。了解各平台的部署命令、缓存策略与自定义域名配置，能让上线流程更加顺畅，并为后续迭代做好准备。

本节将详细介绍各种现代托管平台的部署方式，帮助你选择最适合项目的解决方案。

部署策略概述

Hugo 生成的纯静态文件可以部署到任何支持静态托管的服务。

策略	优点	缺点	适用场景
手动上传	简单直接、完全控制	需手动操作、不便于频繁更新	小型站点、一次性部署
Git 集成	自动构建、版本控制	配置复杂、依赖平台支持	持续更新、团队协作
CI/CD 流水线	高度自动化、可扩展	学习曲线陡峭	大型项目、企业环境

表 1: Hugo 部署策略对比

部署流程总览

GitHub Pages 部署

GitHub Pages 是最简单的免费托管选项，特别适合开源项目。

手动部署

GitHub Pages 手动部署步骤：

构建站点：运行 hugo 命令生成静态文件
创建 gh-pages 分支：使用 git checkout --orphan gh-pages
上传 public 内容：将 public 目录内容添加到分支
启用 GitHub Pages：在仓库设置中选择 gh-pages 分支
配置域名：添加 CNAME 文件或 DNS 配置
访问站点：通过 GitHub Pages URL 访问

# 构建站点
hugo

# 创建 gh-pages 分支并推送
git checkout --orphan gh-pages
git add -A
git commit -m "Deploy Hugo site"
git push origin gh-pages

GitHub Actions 自动部署

# .github/workflows/deploy.yml
name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Netlify 部署

Netlify 提供强大的构建和部署功能，支持 Hugo 的自动检测。

Netlify 部署步骤：

连接 Git 仓库：在 Netlify 中连接你的 GitHub/GitLab 仓库
配置构建设置：设置构建命令和发布目录
设置 Hugo 版本：配置环境变量指定 Hugo 版本
配置环境变量：添加生产环境所需的变量
自动部署：推送代码后自动触发构建和部署
配置域名：添加自定义域名
启用 CDN：利用 Netlify 的全球 CDN 网络

配置步骤

连接仓库：在 Netlify 中连接你的 GitHub/GitLab 仓库
构建设置：
- Build command: hugo --gc --minify
- Publish directory: public
环境变量：
- HUGO_VERSION: 0.147.8
- HUGO_ENV: production

Cloudflare Pages 部署

Cloudflare Pages 提供全球 CDN 和优秀性能。

Cloudflare Pages 部署步骤：

连接仓库：在 Cloudflare Pages 中连接 Git 仓库
配置构建命令：设置 Hugo 构建命令和输出目录
设置环境变量：配置 Hugo 版本和环境变量
自动构建：代码推送后自动触发构建
CDN 分发：通过 Cloudflare 全球 CDN 网络分发
配置域名：添加自定义域名
性能监控：利用 Cloudflare Analytics 监控性能

配置方法

# wrangler.toml (可选)
name = "my-hugo-site"
compatibility_date = "2024-01-01"

[build]
command = "hugo --gc --minify"
cwd = "."

[build.upload]
format = "service-worker"

Vercel 部署

Vercel 针对 Next.js 优化，但也完美支持 Hugo。

Vercel 部署步骤：

导入项目：在 Vercel 中连接 Git 仓库或上传项目
检测 Hugo：Vercel 自动检测 Hugo 项目结构
配置构建：设置构建命令和输出目录
自动部署：代码推送后自动触发构建和部署
全球 CDN：利用 Vercel 的边缘网络分发内容
自定义域名：配置自定义域名和 SSL 证书
预览部署：为每个 PR 创建预览环境

vercel.json 配置

{
  "buildCommand": "hugo --gc --minify",
  "outputDirectory": "public",
  "framework": null,
  "installCommand": "curl -L https://github.com/gohugoio/hugo/releases/download/v0.147.8/hugo_0.147.8_linux-amd64.tar.gz | tar -xz && mv hugo /usr/local/bin/"
}

CI/CD 集成

使用 GitHub Actions 或其他 CI 工具实现自动化部署。

GitHub Actions 示例

name: Deploy Hugo Site

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify --gc

      - name: Deploy to Netlify
        if: github.ref == 'refs/heads/main'
        run: |
          curl -X POST -d '{}' \
            https://api.netlify.com/build_hooks/${{ secrets.NETLIFY_BUILD_HOOK }}

      - name: Deploy to Cloudflare Pages
        if: github.ref == 'refs/heads/main'
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-hugo-site
          directory: public

自定义域名配置

为你的 Hugo 站点配置自定义域名。

平台	配置方法	DNS 设置
GitHub Pages	Repository settings	CNAME 文件或 DNS 配置
Netlify	Site settings	DNS 指向 Netlify nameservers
Cloudflare Pages	Custom domains	DNS 指向 Cloudflare
Vercel	Domains	DNS CNAME 或 A 记录

表 2: 各平台域名配置

HTTPS 配置

HTTPS 配置步骤：

获取证书：通过平台自动获取或上传自定义证书
配置平台：在托管平台中启用 HTTPS 设置
更新 DNS：配置 DNS 记录指向平台域名
验证证书：等待证书验证完成
启用 HTTPS：平台自动配置 SSL/TLS
重定向 HTTP：设置 HTTP 到 HTTPS 的自动重定向

CDN 与缓存策略

优化全球访问速度和性能。

策略	说明	适用场景
边缘缓存	在全球边缘节点缓存内容	静态资源、高访问量
浏览器缓存	利用 HTTP 缓存头	频繁访问的资源
服务端缓存	在源服务器缓存	动态内容（如果有）

表 3: CDN 缓存策略对比

Hugo 缓存配置

# config.yaml
minify:
  disableCSS: false
  disableHTML: false
  disableJS: false
  disableJSON: false
  disableSVG: false
  disableXML: false

caches:
  getjson:
    dir: :cacheDir/:project
    maxAge: 10m
  getresource:
    dir: :cacheDir/:project
    maxAge: 10m

性能监控与优化

部署后的监控和持续优化。

指标	工具	说明
加载速度	Lighthouse	整体性能评分
Core Web Vitals	PageSpeed Insights	用户体验指标
CDN 性能	Cloudflare Analytics	全球访问统计
构建时间	CI/CD 日志	部署效率监控

表 4: 性能监控指标

优化建议

故障排除

部署过程中常见问题及解决方案。

问题	症状	解决方案
构建失败	CI/CD 错误	检查 Hugo 版本、依赖缺失
样式丢失	页面显示异常	验证资源路径、CDN 配置
缓存问题	内容未更新	清除浏览器缓存、刷新 CDN
域名不生效	无法访问	检查 DNS 配置、SSL 证书

表 5: 部署常见问题

总结

Hugo 的部署方式灵活多样，从简单的 GitHub Pages 到功能丰富的 Netlify 和 Cloudflare Pages，每种平台都有其优势。选择合适的部署策略取决于项目规模、预算和技术要求。通过合理配置 CDN 和缓存，可以实现全球快速访问。持续监控性能指标，确保站点始终保持最佳状态。