从 0 搭建一个 Hugo 博客：装 Hugo、装主题、发文章、上线

# Scoop
scoop install hugo-extended

# Chocolatey
choco install hugo-extended

brew install hugo

sudo apt install -y hugo
# 或者用 snap
sudo snap install hugo

hugo version

hugo new site my-blog
cd my-blog
git init

git submodule add https://github.com/LittleWin8/pixel-blog-hugo themes/pixel-blog-hugo

hugo mod init github.com/<你的用户名>/my-blog
hugo mod get github.com/LittleWin8/pixel-blog-hugo

[module]
  [[module.imports]]
    path = "github.com/LittleWin8/pixel-blog-hugo"

baseURL = "https://example.com/"
locale = "zh-cn"
defaultContentLanguage = "zh"
title = "我的博客"
theme = "pixel-blog-hugo"
enableRobotsTXT = true
hasCJKLanguage = true      # 中文站点建议开启（阅读时长/摘要更准）
summaryLength = 80
mainSections = ["posts"]   # 主内容区块：首页最新文章、归档、相关文章、搜索都基于它

[outputs]
  home = ["HTML", "RSS", "JSON"]   # JSON 供站内搜索使用

[pagination]
  pagerSize = 8

[taxonomies]
  tag = "tags"

[markup]
  [markup.goldmark.parser]
    wrapStandAloneImageWithinParagraph = false
  [markup.goldmark.renderer]
    unsafe = true
  [markup.highlight]
    noClasses = false
  [markup.tableofcontents]
    startLevel = 2
    endLevel = 4

[params]
  author = "你的名字"

  [params.identity]        # 顶栏名称与 logo
    name = "你的名字"
    logo = "images/logo.png"     # 放你站点的 assets/images/ 下
    favicon = "images/logo.png"

  [params.hero]            # 首页主视觉文案
    title = "你的名字"
    tagline = "一句话签名"
    intro = "自我介绍，支持 Markdown。"

hugo new posts/hello.md

+++
title = "第一篇：博客开张"
date = 2026-09-29
draft = false          # ← 改成 false 才会正式发布
tags = ["随笔"]
+++

## 小标题

```go
func main() {
    fmt.Println("hello")
}
```

![说明文字](/images/demo.png)

hugo new projects/my-app.md

---
title: "Pixel Notes"
online: true                            # 是否上线（决定绿点与「在线体验」按钮）
link: "https://example.com"             # 「在线体验」按钮
source: "https://github.com/you/repo"   # 「查看源码」按钮
icon: "📝"                              # 卡片图标（emoji 或文字）
tags: ["Vue.js", "TypeScript"]
summary: "一句话介绍。"
---

---
title: "归档"
layout: "archives"
---

hugo server -D

hugo --minify

cd my-blog
git add -A && git commit -m "init blog"
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
git push -u origin main

name: pages
on:
  push:
    branches: [ main ]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          submodules: recursive          # 用 submodule 装主题时必须有
      - name: 安装 Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.166.0'
          extended: true
      - name: 构建
        run: hugo --minify
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

# 1. 本地打包产物
tar -czf /tmp/blog-dist.tar.gz -C public .

# 2. 上传到服务器
scp /tmp/blog-dist.tar.gz root@<服务器IP>:/tmp/

# 3. 服务器上解压覆盖
ssh root@<服务器IP> "rm -rf /opt/blog/* && tar -xzf /tmp/blog-dist.tar.gz -C /opt/blog && rm /tmp/blog-dist.tar.gz"

#!/usr/bin/env bash
set -e
hugo -s ~/my-blog --minify &&
tar -czf /tmp/blog-dist.tar.gz -C ~/my-blog/public . &&
scp /tmp/blog-dist.tar.gz root@<服务器IP>:/tmp/ &&
ssh root@<服务器IP> "rm -rf /opt/blog/* && tar -xzf /tmp/blog-dist.tar.gz -C /opt/blog && rm /tmp/blog-dist.tar.gz" &&
echo "博客已发布"

name: deploy-blog
on:
  push:
    branches: [ main ]
  workflow_dispatch:
permissions:
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          submodules: recursive
      - name: 安装 Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.166.0'
          extended: true
      - name: 构建
        run: hugo --minify
      - name: 配置 SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SERVER_SSH_KEY }}" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          ssh-keyscan -H "${{ secrets.SERVER_HOST }}" >> ~/.ssh/known_hosts
      - name: 发布
        run: |
          tar -czf /tmp/blog-dist.tar.gz -C public .
          scp -i ~/.ssh/deploy_key /tmp/blog-dist.tar.gz root@${{ secrets.SERVER_HOST }}:/tmp/
          ssh -i ~/.ssh/deploy_key root@${{ secrets.SERVER_HOST }} "rm -rf /opt/blog/* && tar -xzf /tmp/blog-dist.tar.gz -C /opt/blog && rm -f /tmp/blog-dist.tar.gz"

# 拉到主题最新提交
git submodule update --remote themes/pixel-blog-hugo

# 提交指针更新（submodule 更新后必须提交，否则只是本地生效）
git add themes/pixel-blog-hugo
git commit -m "chore: 更新主题"

cd themes/pixel-blog-hugo
git fetch origin --tags
git checkout v0.4.1        # 换成你要的版本号
cd ../..
git add themes/pixel-blog-hugo
git commit -m "chore: 更新主题至 v0.4.1"

hugo mod get -u github.com/LittleWin8/pixel-blog-hugo   # 升到最新
# 或指定版本
hugo mod get github.com/LittleWin8/pixel-blog-hugo@v0.4.1