这篇文章记录本站从空目录到上线的完整过程。环境是 Windows + PowerShell 7(命令名 pwsh,不是系统自带的那个)。
在目前状态下,其实自己手搓一个博客其实是一件很简单的事情,只需要向dsh许个愿就行了,但是肯定不如自己做浪费时间:-)。
一、先把环境备齐
四样东西,缺一样都不行:
| 工具 | 版本要求 | 用途 |
|---|---|---|
| PowerShell | 7+,命令名 pwsh | 执行所有命令 |
| Git | 任意较新版本 | 版本管理、推送 |
| Node.js | ≥ 18(建议 22 LTS) | 只用于生成搜索索引 |
| Hugo | ≥ 0.158,extended 版 | 生成静态站 |
顺序建议就按上面这个来:PowerShell 是载体,Git 决定代码能不能推上去,Node 和 Hugo 分别负责搜索索引和构建。
装 PowerShell 7
Windows 自带的那个叫 Windows PowerShell 5.1,命令是 powershell(或 powershell.exe),不要用它。有三个实际影响:
- 不支持
&&串联命令,npm run build && npm run search这类写法直接报语法错 - 默认只开 TLS 1.0/1.1,用
Invoke-WebRequest从 GitHub 下载东西会失败 - 输出编码是 GBK,Hugo 的中文日志、
git log里的中文提交信息容易变成乱码
新版的命令是 pwsh,和 5.1 可以共存,装了不冲突。先用这条判断:
pwsh -v
- 输出
PowerShell 7.x.x→ 已装好,直接用 - 提示
pwsh : 无法将"pwsh"项识别为 cmdlet...→ 没装
装:
winget install --id Microsoft.PowerShell --source winget
winget 不通就去 github.com/PowerShell/PowerShell/releases 下 PowerShell-<版本>-win-x64.msi,双击安装。
装完重开终端,再执行一次 pwsh -v 确认。之后所有命令都在 pwsh 里跑。
VS Code 里顺手把默认终端换过来,否则你每次按 Ctrl + ` 打开的仍然是 5.1:
Ctrl + Shift + P- 输入
Terminal: Select Default Profile - 选 PowerShell 7,不是 Windows PowerShell
装 Git
winget install --id Git.Git -e --source winget
或者去 git-scm.com/download/win 下安装包。安装过程中有个 PATH 选项,要选 Git from the command line and also from 3rd-party software,否则终端里敲 git 会提示找不到命令。
装完重开终端验证:
git --version
然后必须配一下提交身份,否则第一次 git commit 会直接报 Author identity unknown:
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
不想暴露真实邮箱的话,用 GitHub 提供的匿名地址 <ID>+<用户名>@users.noreply.github.com。其中 ID 在 GitHub 的 Settings → Emails 页面能看到。用它提交,记录照样算在你账号名下。
装 Node.js
只有生成搜索索引用得上,不需要写任何前端代码。
winget install --id OpenJS.NodeJS.LTS -e --source winget
装的是 LTS 版,验证:
node -v
npm -v
两个都输出版本号就行。需要同时维护多个 Node 版本可以上 nvm-windows,这个项目用不到。
国内网络如果 npm install 慢,可以换镜像(可选,Hugo 构建本身不依赖 npm 源):
npm config set registry https://registry.npmmirror.com
装 Hugo
winget 最省事:
winget install Hugo.Hugo.Extended
如果 winget 卡住或者公司网络限制了商店,就直接下便携版:
# 到 github.com/gohugoio/hugo/releases 找 hugo_extended_<版本>_windows-amd64.zip
# 解压后把 hugo.exe 放到一个固定目录,比如 D:\hugo\hugo.exe
D:\hugo\hugo.exe version
然后把目录加进用户 PATH(改完要重开终端才生效):
$bin = "D:\hugo"
$p = [Environment]::GetEnvironmentVariable("Path", "User")
if ($p -notlike "*$bin*") {
[Environment]::SetEnvironmentVariable("Path", "$($p.TrimEnd(';'));$bin", "User")
}
最后验一遍
在 pwsh 里依次执行,四条都有输出就说明环境齐了:
pwsh -v
git --version
node -v
hugo version
hugo version 的输出里必须带 +extended:
hugo v0.169.0-1da10fc44701c566b1669cdb2d12638f155138bd+extended windows/amd64
没有 +extended 的部分图片处理(webp 封面等)会失败,主题也可能报错。装了普通版就重装 extended 版。
二、建站
hugo new site my-blog
cd my-blog
git init
Hugo 会生成 archetypes/ content/ layouts/ static/ themes/ hugo.yaml 这一套骨架。hugo.yaml 一开始长这样:
baseURL: https://example.org/
locale: en-us
title: My New Hugo Project
theme:jijian
注意最后一行——这是错的。YAML 里键值之间必须有空格,theme:jijian 会被解析成一个叫 theme:jijian 的键,等于没设主题。我第一次就是这么翻车的,症状是整站渲染成没有任何样式的裸 HTML,而且不报错。
正确写法是 theme: jijian。
装主题
本站用的是极简 jijian ,基于 PaperMod 二次开发,中文排版和搜索做得比较细。用 git submodule 装:
git submodule add https://github.com/hcllmsx/hugo-jijian.git themes/jijian
用 submodule 的好处是主题更新可以直接 git submodule update --remote;代价是克隆仓库时必须带 --recursive,否则 themes/jijian 是个空目录,构建直接失败。CI 里也要显式开启(后面会写)。
三、配置:几个必须改对的地方
完整的 hugo.yaml 比较长,这里只列容易出错的几处。
locale 和分页
locale: zh-cn
defaultContentLanguage: zh-cn
hasCJKLanguage: true
# 新版分页配置,旧的 paginate 键已废弃
pagination:
pagerSize: 10
languageCode 已经被 Hugo 弃用,改用 locale。分页也从顶层的 paginate: 10 改成了 pagination.pagerSize,写旧的虽然还能跑但会有警告。
菜单
menus:
main:
- identifier: posts
name: 文章
url: /posts/
weight: 10
- identifier: archives
name: 时光轴
url: /archives/
weight: 20
这里有个隐性约束:主题会在菜单里做 site.GetPage .KeyName,靠 identifier 反查真实页面。identifier 必须能对应到已存在的页面,否则模板取值拿到 nil,构建会报错。所以 /archives/ 这种菜单项,必须真的建一个 content/archives.md。
PWA manifest 的后缀坑
主题带了 layouts/index.manifest.json,但默认情况下这个文件永远生成不出来,构建日志里会提示:
WARN found no layout file for "manifest" for kind "home"
原因是 Hugo 内置的 application/manifest+json 媒体类型后缀是 webmanifest,而主题模板的文件名是 .json,对不上。解决办法是覆盖媒体类型后缀:
mediaTypes:
application/manifest+json:
suffixes: ["json"]
outputFormats:
manifest:
mediaType: application/manifest+json
baseName: manifest
isPlainText: true
rel: manifest
outputs:
home:
- HTML
- RSS
- manifest
图标别漏
主题的 head.html 里写死了一串默认路径,不补文件就是一排 404:
href="/favicon.ico"
href="/favicon-16x16.png"
href="/favicon-32x32.png"
href="/apple-touch-icon.png"
href="/safari-pinned-tab.svg"
准备这几个文件扔进 static/ 就行。没有现成的图标可以用 Python 的 Pillow 画一个,比找图标站快:
from PIL import Image, ImageDraw, ImageFont
for size in (192, 512):
img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
d = ImageDraw.Draw(img)
d.rounded_rectangle([0, 0, size - 1, size - 1], radius=int(size * 0.22), fill=(31, 35, 40, 255))
font = ImageFont.truetype("C:/Windows/Fonts/segoeuib.ttf", int(size * 0.6))
box = d.textbbox((0, 0), "J", font=font)
w, h = box[2] - box[0], box[3] - box[1]
d.text(((size - w) / 2 - box[0], (size - h) / 2 - box[1]), "J", font=font, fill=(245, 245, 245, 255))
img.save(f"static/icon-{size}.png")
四、写文章
先把固定页面建好,主题靠 layout 字段区分渲染方式:
content/archives.md:
---
title: 时光轴
layout: archives
---
content/search.md:
---
title: 搜索
layout: search
placeholder: 输入关键词,回车搜索
---
这里千不要把 YAML 的冒号打成中文全角冒号。我一开始写的是 title:时光轴,构建不报错,但页面标题是空的——因为全角冒号让整行变成了一个普通字符串,不是键值对。
正文用骨架命令生成:
hugo new content posts/my-first-post.md
默认 draft: true,本地加 -D 能看到,正式构建自动忽略。Front Matter 常用字段:
---
title: 标题
date: 2026-11-13
draft: false
categories: ["技术"]
tags: ["Hugo", "教程"]
summary: 列表页摘要,不写则自动截取
pin: 1 # 置顶,正整数,越小越靠前
ShowToc: true # 是否显示目录
cover:
image: cover.webp
alt: 封面
---
图片直接放在文章同目录(Page Bundle),正文用相对路径引用,主题会自动做灯箱和尺寸处理。
五、搜索:索引不在 hugo server 里
这是最容易误解的一点。主题的搜索用 Pagefind,它是构建后的产物——需要先有静态 HTML,才能扫描建索引。而 hugo server 是在内存里渲染的,public/ 目录里什么都没有,所以本地预览时点搜索框必然是搜不到东西的,这不是配置错了。
正确流程是构建完再跑索引:
hugo --gc --minify
node themes/jijian/scripts/pf-prep.cjs
npx pagefind --site _temp/pf-site --output-path public/pagefind
中间那个 pf-prep.cjs 是主题内置的中文修复脚本。原因是 Pagefind 建索引时按「相邻两字」切分,查询时按整词切分,两本词典不一致,导致「二维码」这类词索引里有、查询时拆成单字就搜不到(Pagefind 的 issue #987)。脚本会在 HTML 文本里插入零宽空格,让两端对齐。
嫌三条命令麻烦就写进 package.json:
{
"scripts": {
"dev": "hugo server -D --disableFastRender",
"build": "hugo --gc --minify",
"search": "node themes/jijian/scripts/pf-prep.cjs && npx pagefind --site _temp/pf-site --output-path public/pagefind",
"preview": "npm run build && npm run search && npx -y serve public"
}
}
想验证搜索效果,用 npm run preview 起一个静态服务,别用 hugo server。
六、部署到 GitHub Pages
这一节全部在浏览器里点,除了 git push 之外不需要任何命令行工具。
先选站点形态
GitHub Pages 有两种地址:
- 用户站点:仓库名必须叫
<用户名>.github.io,地址是https://用户名.github.io/,根路径 - 项目站点:仓库叫任意名字,地址带子目录
https://用户名.github.io/仓库名/
对本站要选第一种。 原因是主题的 baseof.html 里搜索资源的路径是写死根路径的:
<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet">
部署到子目录时,浏览器会去 https://用户名.github.io/pagefind/... 找,而实际文件在 /仓库名/pagefind/...,搜索样式和脚本全 404。除非改主题模板或者绑自定义域名,否则子路径方案搜索一定是坏的。
在网页上建仓库
- 打开
https://github.com/new - Repository name 填
<用户名>.github.io,大小写不影响,但必须和用户名一字不差 - 选 Public(Pages 免费额度只对公开仓库开放)
- 不要勾 Add a README / .gitignore / license,否则本地首次推送会因为历史不一致被拒
- 点 Create repository
建完页面会给你一段 Git 命令提示,先不用管,后面用得上。
准备推送凭据
GitHub 早就不允许用账号密码推送了。三种方式任选其一,都在网页上完成。
方式一:交给 VS Code(最省事)
在 VS Code 里打开这个项目,点左侧「源代码管理」图标,点 Publish Branch。第一次会弹窗让你登录 GitHub,浏览器里授权一次,之后 VS Code 会把凭据存进 Windows 凭据管理器,以后推送不再问。
方式二:个人访问令牌(PAT)
- 右上角头像 → Settings → 左侧最下方 Developer settings
- Personal access tokens → Tokens (classic) → Generate new token (classic)
- Note 随便写,Expiration 选个期限(90 天够用)
- 勾选 repo 和 workflow 两个权限——少勾
workflow的话,CI 文件会因为权限不足推不上去 - 生成后立刻复制,页面刷新就再也看不到这串字符了
推送时用户名填 GitHub 用户名,密码位置粘贴这串 token。
方式三:SSH 密钥
ssh-keygen -t ed25519 -C "你的邮箱"
# 一路回车(密码可留空),然后复制公钥
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard
网页右上角头像 → Settings → SSH and GPG keys → New SSH key → 粘贴 → Add SSH key。
之后远端地址换成 SSH 形式:
git remote add origin git@github.com:<用户名>/<用户名>.github.io.git
推送代码
git add -A
git commit -m "初始化 Hugo 站点"
git branch -M main
git remote add origin https://github.com/<用户名>/<用户名>.github.io.git
git push -u origin main
需要认证时按上一节选的方式填。成功的话终端会显示 main -> main,浏览器刷新仓库就能看到文件。
把 Pages 发布源切成 GitHub Actions
默认 Pages 是「从分支发布」,也就是把仓库里的 HTML 原样发出去。我们的仓库里只有 Markdown 和模板,所以必须改成 Actions 构建。
- 仓库顶部 Settings
- 左侧 Pages
- Build and deployment 下的 Source 下拉,选 GitHub Actions
如果下拉里只有 Deploy from a branch、找不到 GitHub Actions,说明仓库里还没有任何工作流文件。先把下一节的 deploy.yml 提交推送,再刷新这个页面就会出现。
工作流文件
在项目里新建 .github/workflows/deploy.yml:
name: Deploy to GitHub Pages
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
steps:
- name: Checkout
uses: actions/checkout@v7
with:
submodules: recursive # 必须,否则主题目录是空的
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v3
with:
hugo-version: "0.169.0"
extended: true
- name: Setup Node
uses: actions/setup-node@v7
with:
node-version: "22"
cache: npm
- name: Install dependencies
run: npm ci
- name: Configure Pages
id: pages
uses: actions/configure-pages@v6
- name: Build site
run: hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Build search index
run: npm run search
- name: Upload artifact
uses: actions/upload-pages-artifact@v5
with:
path: ./public
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
几个细节值得说:
submodules: recursive别忘了,漏了主题目录为空,构建会报found no layout filebaseURL用configure-pages输出的值,不要写死,换域名时不用改代码npm ci需要仓库里有package-lock.json,否则会用npm install得到不确定的依赖版本- Pagefind 版本固定在
devDependencies里,别用npx -y pagefind@latest,哪天发新版可能行为就变了
覆盖已有站点前先备份
如果这个仓库上已经有别的站点(比如早期的 Hexo),强推会把工作区内容整个换掉。先在网页上打个分支留底:
- 仓库首页 → 分支下拉框 → View all branches
- 右上角 New branch
- 名字填
legacy-hexo,Branch from 选main - Create branch
这个分支就停在旧站的状态。之后强推 main 只会影响 main:
git push -f origin main
哪天想看旧站:
git fetch origin legacy-hexo
git checkout legacy-hexo
看构建结果
- 仓库顶部 Actions
- 左侧选 Deploy to GitHub Pages
- 点最新那条运行记录,能看到
build和deploy两个 job 的每一步
全绿就说明上线了,点开 deploy 页面顶部会显示站点地址。首次部署后地址生效可能需要 1–2 分钟,这期间打开是 404 属于正常。
七、日常流程
上线之后,每天要做的其实只有三件事:
hugo new content posts/xxx.md新建草稿- 本地
hugo server -D预览,写完把draft改成false git push,等 Actions 跑完自动上线
搜索索引、构建、发布都由 CI 接管,本地不需要手动跑 hugo。
八、报错对照表
| 现象 | 原因 | 处理 |
|---|---|---|
| 整站无样式,像裸 HTML | hugo.yaml 里 theme:jijian 少了空格 | 改成 theme: jijian |
| 页面标题空白 | Front Matter 用了中文全角冒号 title: | 换成半角 title: |
命令报 标记"&&"不是此版本中的有效语句分隔符 | 用的是 Windows PowerShell 5.1 | 装 PowerShell 7,改用 pwsh |
git commit 报 Author identity unknown | 没配提交身份 | git config --global user.name 和 user.email |
终端里 node / npm 找不到 | 装的是某个软件自带的 Node,没进系统 PATH | 用 winget 装 OpenJS.NodeJS.LTS |
构建报 found no layout file for "manifest" | manifest 媒体类型后缀是 webmanifest | 在 mediaTypes 里改成 json |
| CI 报主题目录为空 | submodule 没拉取 | checkout 加 submodules: recursive |
| 搜索框样式全丢 | 部署在子路径,/pagefind/ 被解析到根域名 | 改用用户站点或绑自定义域名 |
| 本地预览搜不到内容 | Pagefind 索引是构建产物,hugo server 不生成 | 用 npm run preview 验证 |
| 菜单报 nil pointer | 菜单 identifier 找不到对应页面 | 建好 content/archives.md 这类页面 |
push 报 Authentication failed | 还在用账号密码 | 改用 PAT 或 SSH,见「准备推送凭据」 |
| Pages 的 Source 里没有 GitHub Actions | 仓库里还没有工作流文件 | 先推 deploy.yml,再刷新 Pages 设置 |
push 报 dial tcp ...:443 超时 | 网络无法直连 github.com | 配代理,见下 |
当然遇到的所有报错或者问题都可以向dsh询问解决,不过要注意的一点是,GitHub那里如果不想自己做最好还是用SSH密钥,不然校园网可能会使得你的端口无法正常使用。
附:代理环境下的配置
如果所在网络访问 GitHub 需要代理(我这边就是这样:api.github.com 能直连,但 github.com 超时),只需要配一处:
# 让 git 走本机代理,只影响这个仓库
git config http.proxy http://127.0.0.1:7890
浏览器里的网页操作不用单独设,跟着 Clash 之类的系统代理走就行。
哪天关掉代理后推送报 Failed to connect to 127.0.0.1 port 7890,重新开代理即可;想彻底去掉这条配置就执行:
git config --unset http.proxy
到这里整条链路就通了。剩下的时间应该花在写东西上,而不是修构建。