0020 - 完全手动发布博客指南：从零到上线的原子级操作

一、前置条件检查

在开始前，确认以下工具已安装：

# 检查 Hugo
hugo version
# 预期输出：hugo v0.147.4+extended+withdeploy darwin/arm64 ...

# 检查 Git
git --version
# 预期输出：git version 2.39.0 ...

# 检查 GitHub CLI（可选，用于验证）
gh --version

如果未安装，使用 Homebrew 安装：

brew install hugo git gh

二、项目目录结构理解

~/Documents/blog_wqq/my-tech-blog/    # 博客项目根目录
├── archetypes/                       # 文章模板
├── assets/                           # 需要处理的资源（SCSS、JS）
├── content/                          # ⭐ 文章存放目录
│   └── posts/                        # 博客文章
│       ├── 0001-first-post.md
│       ├── 0002-second-post.md
│       └── ...
├── layouts/                          # HTML 模板
├── static/                           # 静态文件（图片、CSS、JS）
├── themes/                           # 主题目录
│   └── PaperMod/                     # 当前使用的主题
├── hugo.toml                         # ⭐ 博客配置文件
├── new_post.sh                       # 新建文章脚本（可选）
└── publish.sh                        # 发布脚本（可选）

关键目录：

content/posts/ - 你写的 Markdown 文章放这里
hugo.toml - 博客标题、作者、菜单等配置
static/ - 图片等资源放这里，构建后会原样复制到网站

三、创建新文章的完整流程

步骤 1：进入项目目录

cd ~/Documents/blog_wqq/my-tech-blog

步骤 2：确定文章编号

查看已有文章，确定新文章编号：

ls -1 content/posts/ | sort -V | tail -5

输出示例：

0018-kimi-code-cli-capabilities-and-vision.md
0019-weather-widget-top-header-inline.md

→ 下一篇应该是 0020

步骤 3：创建文章文件

使用 Hugo 命令创建（推荐）：

hugo new content/posts/0020-my-new-post.md

或手动创建：

touch content/posts/0020-my-new-post.md

步骤 4：编辑 Front Matter

打开文件，编辑头部元数据：

# 使用 VS Code
code content/posts/0020-my-new-post.md

# 或使用 Vim
vim content/posts/0020-my-new-post.md

# 或使用 Nano
nano content/posts/0020-my-new-post.md

Front Matter 模板：

---
title: "0020 - 文章标题"
date: 2026-03-09T14:35:00+08:00
lastmod: 2026-03-09T14:35:00+08:00
draft: false
math: false
hideSummary: true
tags: ["标签1", "标签2"]
categories: ["技术笔记"]
---

字段说明：

字段	说明	示例
`title`	文章标题	`"0020 - 手动发布指南"`
`date`	发布时间	`2026-03-09T14:35:00+08:00`
`lastmod`	最后修改时间	同 date
`draft`	草稿状态	`false` 发布，`true` 草稿
`math`	是否启用数学公式	`false`
`tags`	标签数组	`["Hugo", "Git"]`
`categories`	分类	`["技术笔记"]`

步骤 5：获取当前时间

Mac 终端执行：

date +%Y-%m-%dT%H:%M:%S%z
# 输出：2026-03-09T14:35:00+0800

注意：将 +0800 改为 +08:00（加冒号）

步骤 6：编写正文内容

在 --- 下方开始写 Markdown 内容：

## 一、引言

这是文章正文...

## 二、详细步骤

1. 第一步
2. 第二步

## 三、代码示例

```bash
echo "Hello World"

四、总结

文章结尾…


### 步骤 7：保存文件

- **VS Code**: `Cmd + S`
- **Vim**: `Esc` → `:wq` → `Enter`
- **Nano**: `Ctrl + O` → `Enter` → `Ctrl + X`

---

## 四、本地预览（可选但推荐）

### 启动 Hugo 开发服务器

```bash
cd ~/Documents/blog_wqq/my-tech-blog
hugo server -D

参数说明：

-D 或 --buildDrafts - 包含草稿文章
--bind 0.0.0.0 - 允许局域网访问
-p 1313 - 指定端口（默认1313）

访问预览

浏览器打开：http://localhost:1313

停止预览

终端中按 Ctrl + C

五、构建网站

步骤 1：清理旧构建

cd ~/Documents/blog_wqq/my-tech-blog
rm -rf public/

步骤 2：执行构建

hugo --minify

参数说明：

--minify - 压缩 HTML/CSS/JS，减小体积

步骤 3：验证构建结果

ls -la public/

应该看到：

index.html          # 首页
posts/              # 文章目录
  └── 0020-my-new-post/
      └── index.html
categories/         # 分类页面
tags/               # 标签页面
...

六、Git 提交与推送

步骤 1：查看变更

cd ~/Documents/blog_wqq/my-tech-blog
git status

输出示例：

Untracked files:
  content/posts/0020-my-new-post.md

步骤 2：添加文件到暂存区

# 添加所有变更
git add -A

# 或只添加特定文件
git add content/posts/0020-my-new-post.md

步骤 3：提交变更

git commit -m "发布文章：手动发布博客指南"

提交信息规范：

发布文章：xxx - 新文章
更新文章：xxx - 修改现有文章
修复：xxx - 修复问题
优化：xxx - 性能或体验优化

步骤 4：推送到 GitHub

git push origin main

可能需要输入 GitHub 凭据或使用 SSH 密钥。

七、验证发布

方法 1：查看 GitHub Actions

访问：https://github.com/Wubajie/wubajie.github.io/actions
确认最新 workflow 运行成功（绿色 ✓）

方法 2：直接访问网站

等待 1-2 分钟后访问：

首页：https://wubajie.github.io/
新文章：https://wubajie.github.io/posts/0020-my-new-post/

方法 3：检查 RSS

curl https://wubajie.github.io/index.xml | grep "0020"

八、完整命令速查表

一键发布脚本（手动版）

#!/bin/bash
# 保存为 publish_manual.sh

cd ~/Documents/blog_wqq/my-tech-blog

echo "🧹 清理旧构建..."
rm -rf public/

echo "🏗️ 构建网站..."
hugo --minify

echo "📦 Git 提交..."
git add -A
git commit -m "发布文章：$1"

echo "🚀 推送到 GitHub..."
git push origin main

echo "✅ 完成！等待 GitHub Actions 部署..."

使用方法：

chmod +x publish_manual.sh
./publish_manual.sh "手动发布博客指南"

常用命令汇总

# 进入目录
cd ~/Documents/blog_wqq/my-tech-blog

# 新建文章
hugo new content/posts/0021-next-post.md

# 本地预览
hugo server -D

# 构建
rm -rf public/ && hugo --minify

# Git 提交流程
git add -A
git commit -m "提交信息"
git push origin main

# 查看状态
git status
git log --oneline -5

九、常见问题排查

Q1: 文章没有显示？

检查清单：

draft: false 不是 true
文件保存在 content/posts/ 目录
文件名格式正确：0020-title.md
已执行 hugo --minify
已 git push
GitHub Actions 运行成功

Q2: 时间格式错误？

正确格式：

date: 2026-03-09T14:35:00+08:00

常见错误：

❌ 2026-03-09 14:35:00（缺少 T）
❌ 2026-03-09T14:35:00+0800（时区缺少冒号）

Q3: 构建失败？

# 查看详细错误
hugo --verbose

# 检查配置文件
hugo config

Q4: 推送被拒绝？

# 先拉取最新代码
git pull origin main

# 解决冲突后重新推送
git push origin main

十、文件模板速记

新文章模板

---
title: "00XX - 文章标题"
date: YYYY-MM-DDTHH:MM:SS+08:00
lastmod: YYYY-MM-DDTHH:MM:SS+08:00
draft: false
math: false
hideSummary: true
tags: ["标签1", "标签2"]
categories: ["技术笔记"]
---

## 一、

内容...

## 二、

内容...

## 三、总结

总结...

十一、总结

手动发布博客的原子级步骤：

写 - 在 content/posts/ 创建 Markdown 文件
配 - 编辑 Front Matter（标题、时间、标签）
构 - 运行 hugo --minify 生成网站
提 - git add -A && git commit -m "xxx"
推 - git push origin main
等 - 等待 GitHub Actions 部署（约1分钟）
验 - 访问网站验证

掌握这 7 步，完全脱离 AI 也能独立发布博客！

一、前置条件检查#

二、项目目录结构理解#

三、创建新文章的完整流程#

步骤 1：进入项目目录#

步骤 2：确定文章编号#

步骤 3：创建文章文件#

步骤 4：编辑 Front Matter#

步骤 5：获取当前时间#

步骤 6：编写正文内容#

四、总结#

访问预览#

停止预览#

五、构建网站#

步骤 1：清理旧构建#

步骤 2：执行构建#

步骤 3：验证构建结果#

六、Git 提交与推送#

步骤 1：查看变更#

步骤 2：添加文件到暂存区#

步骤 3：提交变更#

步骤 4：推送到 GitHub#

七、验证发布#

方法 1：查看 GitHub Actions#

方法 2：直接访问网站#

方法 3：检查 RSS#

八、完整命令速查表#

一键发布脚本（手动版）#

常用命令汇总#

九、常见问题排查#

Q1: 文章没有显示？#

Q2: 时间格式错误？#

Q3: 构建失败？#

Q4: 推送被拒绝？#

十、文件模板速记#

新文章模板#

十一、总结#