Hugo 静态网站构建实战手册

自动化部署

将 Hugo 站点部署到 GitHub Pages、Netlify、Vercel、Cloudflare Pages 和自有服务器

自动化部署

Hugo 构建后的输出目录默认是 public/。部署的本质就是把 public/ 里的静态文件发布到托管平台。

推荐工作流：

本地写作
  ↓
git push
  ↓
托管平台拉取仓库
  ↓
安装 Hugo、Node、Go 等构建依赖
  ↓
hugo --gc --minify
  ↓
发布 public/

部署前检查

hugo --gc --minify

确认：

  • 本地构建成功
  • baseURL 是线上域名或部署平台提供的预览 URL
  • 线上 Hugo 版本与本地一致
  • 主题 submodule 或 Hugo Modules 可以被 CI 拉取
  • public/ 不提交到源码仓库
  • 草稿、未来文章、测试内容不会进入正式构建

.gitignore：

/public/
/resources/
/.hugo_build.lock

固定 Hugo 版本

Hugo 版本变化可能影响模板函数、资源管道和主题兼容性。部署环境建议固定版本。

本文按 2026 年 6 月官方文档整理，Hugo GitHub Releases 当前最新稳定版为 0.163.0。

常见环境变量：

HUGO_VERSION=0.163.0
HUGO_ENVIRONMENT=production
TZ=Asia/Shanghai

如果主题需要 Dart Sass、PostCSS、Tailwind 或 Hugo Modules，还要配置对应版本和安装步骤。

GitHub Pages

GitHub Pages 推荐使用 GitHub Actions 构建和部署。先到仓库：

Settings -> Pages -> Source -> GitHub Actions

创建 .github/workflows/hugo.yaml：

name: Build and deploy Hugo

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.163.0
      HUGO_ENVIRONMENT: production
      TZ: Asia/Shanghai
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v6

      - name: Install Hugo
        run: |
          curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          mkdir "${HOME}/hugo"
          tar -C "${HOME}/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          echo "${HOME}/hugo" >> "${GITHUB_PATH}"

      - name: Install Node dependencies
        run: |
          [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true

      - name: Build
        run: |
          hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

如果你的站点使用 Hugo Modules，添加 Go：

- name: Setup Go
  uses: actions/setup-go@v6
  with:
    go-version: '1.26.3'

如果使用 Dart Sass，需要在构建前安装 Dart Sass。Hugo 官方 GitHub Pages 文档提供了完整示例，可以按主题需求扩展。

Netlify

创建 netlify.toml：

[build.environment]
  HUGO_VERSION = "0.163.0"
  HUGO_ENVIRONMENT = "production"
  NODE_VERSION = "24.16.0"
  GO_VERSION = "1.26.3"
  TZ = "Asia/Shanghai"

[build]
  publish = "public"
  command = "hugo --gc --minify --baseURL \"$URL\""

如果使用 npm 依赖：

[build]
  publish = "public"
  command = "npm ci && hugo --gc --minify --baseURL \"$URL\""

如果使用 Dart Sass，要先安装 Dart Sass，再执行 Hugo。可参考 Hugo 官方 Netlify 文档中的完整脚本。

Netlify 常见设置：

项目值
Build commandhugo --gc --minify
Publish directorypublic
Hugo versionHUGO_VERSION=0.163.0

Vercel

Vercel 可以自动识别 Hugo 项目。导入 Git 仓库后，通常使用：

项目值
Framework PresetHugo
Build Commandhugo --gc --minify
Output Directorypublic
Install Command按项目需要，常见为 npm ci

建议在项目环境变量中设置：

HUGO_VERSION=0.163.0
HUGO_ENVIRONMENT=production

也可以创建 vercel.json：

{
  "buildCommand": "hugo --gc --minify",
  "outputDirectory": "public",
  "installCommand": "npm ci || true"
}

如果使用 Git submodule，确认 Vercel 能拉取 submodule。公开主题通常没问题；私有主题需要配置访问权限。

Cloudflare Pages

Cloudflare Pages 设置：

项目值
Production branchmain
Build commandhugo --gc --minify
Build output directorypublic

环境变量：

HUGO_VERSION=0.163.0
HUGO_ENVIRONMENT=production
TZ=Asia/Shanghai

Cloudflare Pages 提供 CF_PAGES_URL，预览部署时可以用它作为 baseURL：

hugo --gc --minify --baseURL "$CF_PAGES_URL"

如果生产域名已固定，可以在生产环境使用真实域名，在预览环境使用 CF_PAGES_URL。

Cloudflare Workers Static Assets

Hugo 官方文档也提供了 Cloudflare Workers 静态资源部署方式。适合需要 Workers 能力的项目。

最小 wrangler.toml：

name = "my-hugo-site"
compatibility_date = "2026-06-10"

[assets]
directory = "./public"
not_found_handling = "404-page"

构建：

hugo --gc --minify
npx wrangler deploy

只需要静态站时，Cloudflare Pages 更简单；需要 Workers 路由、边缘逻辑或更复杂控制时，再考虑 Workers。

自有服务器

构建：

hugo --gc --minify

用 rsync 上传：

rsync -avz --delete public/ user@example.com:/var/www/example.org/

Nginx 示例：

server {
  listen 80;
  server_name example.org www.example.org;
  root /var/www/example.org;
  index index.html;

  location / {
    try_files $uri $uri/ =404;
  }

  location ~* \.(css|js|jpg|jpeg|png|gif|webp|svg|woff2?)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

HTTPS 建议使用 Caddy 自动证书，或 Nginx + Certbot。

baseURL 策略

baseURL 决定 canonical、RSS、Sitemap、绝对链接和部分资源地址。

生产站点：

baseURL = 'https://example.org/'

CI 临时覆盖：

hugo --baseURL https://example.org/

预览环境：

hugo --baseURL "$DEPLOY_PRIME_URL"

Netlify 常见变量：

  • URL 生产站点 URL
  • DEPLOY_PRIME_URL 当前部署 URL

Cloudflare Pages 常见变量：

  • CF_PAGES_URL 当前 Pages URL

私有主题和 submodule

如果主题使用 Git submodule：

git submodule update --init --recursive

CI checkout 要启用 submodule：

with:
  submodules: recursive

私有主题要配置：

  • GitHub Deploy Key
  • Personal Access Token
  • 平台提供的私有子模块访问设置

如果 submodule 经常让部署复杂，可以考虑 Hugo Modules 或把主题 fork 到同一组织。

部署常见问题

Q: 本地正常，线上构建失败

A: 优先检查 Hugo 版本、Extended 版本、Node/Go/Dart Sass 是否安装，以及主题 submodule 是否拉取。

Q: 线上样式丢失

A: 检查 baseURL、主题是否安装、资源路径是否写死为错误域名。

Q: 页面部署成功但 404

A: 检查输出目录是否是 public，仓库 Pages Source 是否设置为 GitHub Actions，平台发布目录是否填错。

Q: 新文章没有上线

A: 检查 draft: true、未来日期、构建日志和缓存。正式构建默认跳过草稿。

Q: 中文文件名或路径乱码

A: CI 中可以设置：

git config core.quotepath false

也建议文章 URL 使用英文 slug。

推荐部署方案

使用场景推荐平台
纯博客、开源项目文档GitHub Pages
希望配置简单、表单和重定向强Netlify
需要预览部署和前端团队协作Vercel
已使用 Cloudflare DNS/CDNCloudflare Pages
需要完全控制服务器自有服务器

下一步

继续阅读 故障排除，遇到构建或显示问题时按清单定位。

评论

0%