Hugo 是 Go 生态中最流行的静态站点生成器，构建速度极快、功能丰富且易于扩展。本文将带你从 0 → 1 完成以下目标：
- 安装 Hugo 与必要工具
- 创建站点并选择主题（以 Blowfish 为例）
- 本地写作与实时预览
- 资源优化与多语言配置
- GitHub Pages 自动部署上线
- 常见问题 FAQ
1. 环境准备#
1.1 安装 Hugo#
| 平台 | 推荐安装方式 |
|---|---|
| macOS | brew install hugo |
| Windows | scoop
：scoop install hugo-extended |
| Linux | 官方二进制 or snap install hugo |
# 检查版本（需 0.115+ 才含 ESBuild）
hugo version
Tip：如需处理 Sass/SCSS，务必安装 Extended 版本。
1.2 安装 Git 与 Node.js#
- Git：管理主题、自动部署代码
- Node.js：部分主题或工具（如
blowfish-tools）需用到
brew install git node # macOS 示例
2. 创建 Hugo 站点#
# 任意目录执行
hugo new site myblog && cd myblog
生成的目录结构：
myblog/
├── archetypes/ # 内容模版
├── content/ # Markdown 文章
├── layouts/ # 自定义模板
├── themes/ # 第三方主题存放
└── hugo.toml # 站点基础配置
3. 选择并安装主题（Blowfish）#
Hugo 生态拥有数百款主题，这里以功能强大的 Blowfish 为例，它内置暗色模式、Tailwind、搜索、短代码等特性。
3.1 作为 Git 子模块引入#
git init -b main # 若未初始化仓库
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
使用子模块的好处：主题与文章分离，后期升级只需
git submodule update --remote。
3.2 复制示例配置#
mkdir -p config/_default
cp -r themes/blowfish/exampleSite/config/_default/* config/_default/
rm hugo.toml # 删除根部旧配置（示例已包含新的）
关键文件概览：
hugo.toml：基础参数（baseURL、security等）params.toml：主题功能开关（颜色方案、搜索、Header 等）menus.*.toml：导航菜单languages.*.toml：多语言元数据
4. 本地实时预览#
hugo server --disableFastRender -D
打开 http://localhost:1313
即可实时查看。-D 选项允许渲染 draft = true 的草稿文章。
5. 开始写作#
5.1 创建首篇文章#
hugo new posts/hello-hugo.md
编辑生成的 content/posts/hello-hugo.md：
---
title: "Hello Hugo!"
date: 2025-07-01
featured: true # Blowfish 将自动识别特色图片
summary: "我的第一篇 Hugo 文章"
tags: ["随笔"]
---
在这里撰写正文 …
5.2 添加封面/缩略图#
将图片命名为 featured.* 或 cover.* 丢到文章同级目录即可，Blowfish 会自动裁剪生成多尺寸缩略图并用于社交媒体卡片。
6. 站点高级配置#
6.1 颜色方案与暗黑模式#
在 params.toml 中设置：
colorScheme = "neon" # 预设：blowfish | avocado | ocean ...
并可通过 defaultAppearance 与 autoSwitchAppearance 控制暗亮模式。
6.2 多作者 & 多语言#
content/authors/steven/_index.md可添加作者档案- 复制
languages.en.toml改为languages.zh-cn.toml即可开启多语言
6.3 自定义域名与 HTTPS#
若部署到 GitHub Pages，可在仓库设置中添加 自定义域名，并开启"Enforce HTTPS"。
7. GitHub Pages 自动部署#
在仓库根新建 .github/workflows/deploy.yml：
name: Deploy Hugo site to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
submodules: recursive
- uses: peaceiris/actions-hugo@v2
with:
hugo-version: latest
extended: true
- run: hugo --minify --gc
- uses: actions/upload-pages-artifact@v3
with:
path: ./public
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/deploy-pages@v4
推送后，GitHub Actions 会自动执行构建并将静态文件发布到 gh-pages 环境。
💡 若希望使用 Cloudflare Pages、Vercel 等平台，原理相同，只需更换 CI/CD 模板。
8. 性能优化 Tips#
- 图片懒加载：Blowfish 默认启用
loading="lazy"。若需占位渐进加载，可结合 blurhash 。 - 压缩与指纹：
hugo --minify --gc自动去除未用资源并压缩 HTML/CSS/JS。 - 资源缓存：利用 Cloudflare / BunnyCDN 配置长缓存头 + 自动 Brotli/Gzip。
- PWA：安装 vite-plugin-pwa 或 Hugo 的 workbox 实现离线缓存。
9. 常见问题 FAQ#
| 问题 | 解决方案 |
|---|---|
构建时提示 failed to load translations | 确认 i18n/ 目录存在默认 *.yaml，或在 hugo.toml 关闭相关语言 |
| 子模块无法拉取 | git submodule update --init --recursive，或检查代理 |
| CSS 未生效 | 使用 Extended 版本；确保未误删 assets/css/*.scss |
| 文章排版错乱 | 检查 Markdown 列表缩进；使用 markdownRenderHooks 自定义 |
10. 结语#
以上就是 完整、现代化的 Hugo 博客搭建流程。如果你遇到其他问题，欢迎：
- 阅读官方文档：https://gohugo.io/documentation/
- 查看 Blowfish 主题文档：https://blowfish.page/docs/
- 在评论区留言或 Issue 提问 🙌
祝你写作顺利，博客常青！