Windows 部署 Hugo 博客 🚀

1

winget install --id Hugo.Hugo.Extended -e --source winget --accept-package-agreements --accept-source-agreements; hugo version

1
2
3
4
5

# 打开 Windows 终端（PowerShell 或 CMD）
hugo version

# 应该显示类似以下信息：
# hugo v0.140.0-7d2e48e6d4a922e2f4b0724d7ea5e838517d8e5a windows/amd64 BuildDate=2024-05-22T09:45:36Z VendorInfo=gohugoio

1
2
3
4
5
6
7
8

# 下载并安装 Git for Windows
# 访问：https://git-scm.com/download/win

# 一条命令安装 Git
winget install --id Git.Git -e --source winget --accept-package-agreements

# 验证 Git 安装
git --version

1
2
3
4
5
6
7
8
9

# 打开 PowerShell 或 CMD
# 进入 Hugo 安装目录
cd C:\hugo

# 创建新的博客站点
hugo new site myblog

# 进入站点目录
cd myblog

1
2
3
4
5
6
7

# 初始化 Git 仓库
git init

# 创建 .gitignore 文件
echo "public/" > .gitignore
echo "resources/" >> .gitignore
echo ".hugo_build.lock" >> .gitignore

1
2
3
4

# 创建新文章
hugo new posts/myblog-001.md

# 📝 文章保存在：C:\hugo\myblog\content\posts\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
title: "My First Blog Post"
date: 2024-05-25T15:30:00+08:00
draft: false
author: "Your Name"
description: "这是我的第一篇 Hugo 博客文章"
tags: ["hugo", "blog", "first"]
categories: ["技术"]
---

## 欢迎来到我的博客！

这是使用 Hugo 创建的第一篇文章。

### 功能特点

- ⚡ 极速构建
- 🎨 丰富主题
- 📱 响应式设计
- 🌍 多语言支持

### 代码示例

```python
def hello_world():
    print("Hello, Hugo!")
    return True

1
2
3
4
5
6
7
8
9

### 5️⃣ 本地预览站点

```bash
# 启动本地服务器
hugo server -D

# 🌐 浏览器访问：http://localhost:1313/
# 🔄 支持热重载，修改内容自动刷新

1
2
3
4
5

# 进入站点目录
cd C:\hugo\myblog

# 添加主题作为 Git 子模块
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 基本配置
baseURL = "https://yourdomain.com/"
languageCode = "zh-cn"
title = "我的 Hugo 博客"
theme = "ananke"

# 主题特定配置
[params]
  description = "这是我的 Hugo 博客"
  author = "Your Name"
  github = "yourgithub"
  twitter = "yourtwitter"
  
# 菜单配置
[menu]
  [[menu.main]]
    identifier = "posts"
    name = "文章"
    url = "/posts/"
    weight = 1
    
  [[menu.main]]
    identifier = "tags"
    name = "标签"
    url = "/tags/"
    weight = 2
    
  [[menu.main]]
    identifier = "about"
    name = "关于"
    url = "/about/"
    weight = 3

# 社交媒体链接
[[params.social]]
  name = "GitHub"
  url = "https://github.com/yourname"

[[params.social]]
  name = "Twitter"
  url = "https://twitter.com/yourname"

1
2
3
4
5
6
7
8

# 创建布局覆盖目录
mkdir -p layouts/partials

# 复制主题文件进行自定义
cp themes/ananke/layouts/partials/header.html layouts/partials/

# 编辑自定义文件
# 修改 layouts/partials/header.html 添加自定义内容

1
2
3
4
5

# 启动开发服务器
hugo server -D

# 在浏览器中查看效果
# 访问：http://localhost:1313/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 检查 Docker 是否安装
docker --version

# 检查 Docker Compose 是否安装
docker-compose --version

# 如果没有安装，请先安装
# Ubuntu/Debian 安装命令：
sudo apt update
sudo apt install docker.io docker-compose -y

1
2
3
4
5
6
7
8

# 创建 Hugo 部署目录
sudo mkdir -p /mnt/mydisk/home/hugo/public

# 设置目录权限
sudo chown -R $USER:$USER /mnt/mydisk/home/hugo

# 创建 docker-compose.yml 文件
nano /mnt/mydisk/home/hugo/docker-compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# /mnt/mydisk/home/hugo/docker-compose.yml
version: '3.8'

services:
  hugoweb:
    image: nginx:alpine
    container_name: hugonx
    restart: unless-stopped
    ports:
      - "7080:80"
    volumes:
      - ./public:/usr/share/nginx/html:ro
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./logs:/var/log/nginx
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80
    networks:
      - hugo-network

networks:
  hugo-network:
    driver: bridge

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# /mnt/mydisk/home/hugo/nginx.conf
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    
    access_log /var/log/nginx/access.log main;
    
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;
    
    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript 
               application/javascript application/xml+rss 
               application/json image/svg+xml;
    
    # 静态文件缓存
    server {
        listen 80;
        server_name localhost;
        root /usr/share/nginx/html;
        index index.html index.htm;
        
        # 缓存静态资源
        location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
        
        # 处理 SPA 路由
        location / {
            try_files $uri $uri/ /index.html;
        }
        
        # 禁止访问隐藏文件
        location ~ /\. {
            deny all;
            return 404;
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 进入项目目录
cd /mnt/mydisk/home/hugo

# 构建并启动容器
docker-compose up -d

# 查看容器状态
docker-compose ps

# 查看容器日志
docker-compose logs -f

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 停止 hugonx 容器
docker stop hugonx

# 启动 hugonx 容器
docker start hugonx

# 重启 hugonx 容器
docker restart hugonx

# 删除容器
docker rm hugonx

# 删除容器和卷
docker rm -v hugonx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 进入容器内部（使用 bash）
docker exec -it hugonx bash

# 进入容器内部（使用 sh）
docker exec -it hugonx sh

# 在容器中执行命令
docker exec hugonx nginx -t

# 查看容器资源使用
docker stats hugonx

# 📝 使用 Ctrl+D 退出容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 查看容器日志
docker logs hugonx

# 实时查看日志
docker logs -f hugonx

# 查看最后N行日志
docker logs --tail 100 hugonx

# 查看特定时间后的日志
docker logs --since 2024-05-25T10:00:00 hugonx

# 清空容器日志（需要进入容器）
docker exec hugonx sh -c 'echo "" > /var/log/nginx/access.log'
docker exec hugonx sh -c 'echo "" > /var/log/nginx/error.log'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 备份容器数据
docker cp hugonx:/usr/share/nginx/html ./backup-$(date +%Y%m%d)

# 备份 Nginx 配置
docker cp hugonx:/etc/nginx/nginx.conf ./nginx-backup-$(date +%Y%m%d).conf

# 创建容器快照
docker commit hugonx hugonx-backup:$(date +%Y%m%d)

# 从快照恢复
docker run -d --name hugonx-restored -p 7080:80 hugonx-backup:20240525

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 在 Windows 端生成静态文件
cd C:\hugo\myblog

# 构建站点（发布模式）
hugo --minify

# 或者构建包含草稿的文章
hugo -D --minify

# 📁 生成的文件在：C:\hugo\myblog\public\

1
2
3
4
5
6
7
8

# 在 Windows PowerShell 或 CMD 中
# 安装 OpenSSH 客户端（如果尚未安装）

# 同步文件到服务器
scp -r C:\hugo\myblog\public\* user@yourserver.com:/mnt/mydisk/home/hugo/public/

# 或者使用 rsync（需要安装）
rsync -avz --delete C:\hugo\myblog\public/ user@yourserver.com:/mnt/mydisk/home/hugo/public/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# 在服务器上创建 Git 钩子
# 1. 在服务器上初始化裸仓库
cd /mnt/mydisk/home
git init --bare hugo.git

# 2. 创建钩子脚本
nano hugo.git/hooks/post-receive

# 添加以下内容：
#!/bin/bash
TARGET="/mnt/mydisk/home/hugo/public"
GIT_DIR="/mnt/mydisk/home/hugo.git"
BRANCH="main"

while read oldrev newrev ref
do
    if [[ $ref =~ .*/$BRANCH$ ]];
    then
        echo "Ref $ref received. Deploying ${BRANCH} branch to production..."
        git --work-tree=$TARGET --git-dir=$GIT_DIR checkout -f $BRANCH
    else
        echo "Ref $ref received. Doing nothing: only the ${BRANCH} branch may be deployed on this server."
    fi
done

# 3. 设置执行权限
chmod +x hugo.git/hooks/post-receive

# 在 Windows 端添加远程仓库
cd C:\hugo\myblog
git remote add production user@yourserver.com:/mnt/mydisk/home/hugo.git

# 推送更改
git add .
git commit -m "更新博客内容"
git push production main

1
2
3
4
5
6
7
8
9

# 服务器端重启容器
docker restart hugonx

# 或者使用 Docker Compose
cd /mnt/mydisk/home/hugo
docker-compose restart

# 验证服务状态
curl -I http://localhost:7080

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@echo off
echo [INFO] 开始构建 Hugo 站点...
cd C:\hugo\myblog

echo [INFO] 生成静态文件...
hugo --minify

echo [INFO] 同步到服务器...
rsync -avz --delete public/ user@yourserver.com:/mnt/mydisk/home/hugo/public/

echo [INFO] 重启 Docker 容器...
ssh user@yourserver.com "cd /mnt/mydisk/home/hugo && docker-compose restart"

echo [INFO] 部署完成!
pause

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Write-Host "开始构建 Hugo 站点..." -ForegroundColor Green
Set-Location C:\hugo\myblog

# 生成静态文件
hugo --minify

if ($LASTEXITCODE -eq 0) {
    Write-Host "静态文件生成成功" -ForegroundColor Green
    
    # 同步到服务器
    $result = scp -r public/* user@yourserver.com:/mnt/mydisk/home/hugo/public/
    
    if ($LASTEXITCODE -eq 0) {
        Write-Host "文件同步成功" -ForegroundColor Green
        
        # 重启容器
        $restart = ssh user@yourserver.com "cd /mnt/mydisk/home/hugo && docker-compose restart"
        Write-Host "Docker 容器已重启" -ForegroundColor Green
    } else {
        Write-Host "文件同步失败" -ForegroundColor Red
    }
} else {
    Write-Host "静态文件生成失败" -ForegroundColor Red
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 初始化 Git 仓库
cd C:\hugo\myblog
git init

# 创建 .gitignore 文件
cat > .gitignore << EOF
# Hugo 忽略文件
public/
resources/
.hugo_build.lock

# 操作系统文件
.DS_Store
Thumbs.db

# 编辑器文件
.vscode/
.idea/
*.swp
*.swo
EOF

# 添加所有文件
git add .

# 提交初始版本
git commit -m "初始提交: 创建 Hugo 博客"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 创建自定义布局
mkdir -p layouts/_default

# 覆盖主题的 baseof 模板
cp themes/ananke/layouts/_default/baseof.html layouts/_default/

# 创建自定义短代码
mkdir -p layouts/shortcodes
cat > layouts/shortcodes/notice.html << EOF
<div class="notice {{ .Get 0 }}">
    {{ .Inner }}
</div>
EOF

# 在文章中使用短代码
# {{ notice warning }}
# 这是一个警告提示
# {{ /notice }}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 使用构建缓存
hugo --gc --minify

# 启用构建分析
hugo --buildFuture --buildDrafts --buildExpired

# 生成站点地图
cat > config.toml << EOF
[sitemap]
  changefreq = "monthly"
  priority = 0.5
  filename = "sitemap.xml"
EOF

# 优化图片处理
# 安装 Hugo 图片处理扩展
# 在 config.toml 中配置：
[imaging]
  resampleFilter = "CatmullRom"
  quality = 75
  anchor = "smart"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 在 config.toml 中配置 SEO
[params]
  seo = true
  googleAnalytics = "UA-XXXXXXXXX-X"
  
[params.openGraph]
  locale = "zh_CN"
  siteName = "我的 Hugo 博客"
  
[params.twitter]
  creator = "@yourtwitter"
  site = "@yourtwitter"

1
2
3
4
5
6
7
8

# 检查端口占用
netstat -ano | findstr :7080

# 终止占用进程
taskkill /PID <PID> /F

# 或者修改 docker-compose.yml 中的端口映射
# 将 "7080:80" 改为 "8080:80" 或其他端口

1
2
3
4
5
6

# 服务器端权限修复
sudo chown -R $USER:$USER /mnt/mydisk/home/hugo
sudo chmod -R 755 /mnt/mydisk/home/hugo/public

# Windows 端文件权限问题
# 以管理员身份运行 PowerShell 或 CMD

1
2
3
4
5
6
7
8

# 检查主题是否正确安装
ls themes/

# 检查 config.toml 中的主题配置
cat config.toml | grep theme

# 重新初始化主题子模块
git submodule update --init --recursive

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 查看详细错误信息
hugo --verbose

# 调试模式
hugo --debug

# 清除缓存重新构建
hugo --ignoreCache

# 检查文件语法
hugo check

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 查看容器日志
docker logs hugonx

# 检查容器状态
docker inspect hugonx

# 重新构建容器
docker-compose down
docker-compose up -d --build

# 检查端口映射
docker port hugonx

1
2
3
4
5
6
7
8

# 强制清除浏览器缓存
Ctrl + F5 (Windows) 或 Cmd + Shift + R (Mac)

# 检查 Nginx 缓存配置
# 确保没有过度缓存静态文件

# 重启 Nginx 容器
docker exec hugonx nginx -s reload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 购买域名并配置 DNS
# 将域名解析到服务器 IP

# 修改 Nginx 配置
server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    # ... 其他配置
}

# 更新 Hugo 配置
baseURL = "https://yourdomain.com/"

1
2
3
4
5
6
7
8
9

# 使用 Let's Encrypt 获取免费 SSL 证书
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

# 自动续期证书
sudo crontab -e
# 添加：0 12 * * * /usr/bin/certbot renew --quiet

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 自动化备份脚本
#!/bin/bash
# backup-hugo.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/hugo"

# 备份内容
tar -czf $BACKUP_DIR/hugo-content-$DATE.tar.gz /mnt/mydisk/home/hugo/

# 备份数据库（如果有）
# docker exec some-mysql sh -c 'exec mysqldump --all-databases' > $BACKUP_DIR/mysql-$DATE.sql

# 删除旧备份（保留最近30天）
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

echo "备份完成: $BACKUP_DIR/hugo-content-$DATE.tar.gz"