4.7 KiB

Raw Blame History

🚀 我的 Hugo 博客操作手册

这份文档是为了防止我忘记 Hugo 指令而准备的“防呆”指南。

1. 常用开发指令 (本地电脑)

在进行任何操作前，请先进入博客的根目录（即本文件所在的文件夹）。

🛠️ 启动本地预览（最常用）

hugo server -D

作用：在本地运行一个实时预览服务器。
参数 -D：表示显示标记为 draft: true（草稿）的文章。
查看地址：在浏览器输入 http://localhost:1313/。
注意：这个命令是动态的，你修改并保存 Markdown 文件后，浏览器会自动刷新。

📝 新建一篇文章

hugo new posts/我的第一篇博客.md

作用：在 content/posts/ 目录下创建一个新的 Markdown 文件，并带上基础的模板（元数据）。
建议：文件名尽量不要有空格，可以使用中划线，如 my-first-post.md。

🏗️ 生成静态 HTML 文件

hugo

作用：将你的所有 Markdown 源码正式编译成 HTML/CSS/JS。
产出：所有的静态文件都会生成在根目录下的 public/ 文件夹中。
场景：当你准备把网站更新到服务器上时，才运行这个命令。

2. 关于“写文章”的说明

💡 我可以直接把写好的 .md 挪进来吗？

可以！ 你不需要非得用 hugo new 指令。你可以直接把写好的 Markdown 文件直接拖进 content/posts/ 目录下。

但是（非常重要）： Hugo 识别文章是靠 Markdown 文件头部的 Front Matter（元数据）。如果你直接挪文件，请务必在文章最顶部加上这段代码（以 YAML 格式为例）：

---
title: "文章标题"
date: 2023-10-27T10:00:00+08:00
draft: false
tags: ["标签1", "标签2"]
categories: ["分类"]
---

draft: true：如果是 true，生成网站时这篇文章会被忽略（除非你带了 -D 参数）。
date：Hugo 默认按照这个时间排序，如果时间是未来的时间，文章也不会显示。

3. 本地 vs 生产环境 (Linux 服务器)

你在本地电脑和在 Linux 服务器上的操作可能略有不同，取决于你的部署方式。

场景 A：在本地生成，上传 `public` 文件夹

这是最简单的方式。

本地运行 hugo。
使用 FTP/SCP/Rsync 将本地生成的 public/ 文件夹里的所有内容发到 Linux 服务器的 Web 目录（如 /var/www/html）。
优势：服务器不需要安装 Hugo。

场景 B：在服务器上通过源码生成

如果你在服务器上也安装了 Hugo，并且通过 Git 同步代码：

在服务器执行 git pull 同步源码。
在服务器执行 hugo（不需要带 server）。
确保你的 Nginx/Apache 指向的是服务器上的 public 目录。

⚠️ 区别提醒

Hugo 版本：确保本地和服务器的 Hugo 版本尽量一致，尤其是 Extended 版本（如果你使用了高级的 CSS 样式）。
BaseURL：在根目录的 hugo.toml (或 config.toml) 中，baseURL 必须写成你真实的域名（如 https://www.example.com/），否则服务器上的图片或样式可能加载不出来。

4. 常见问题排查 (新人必看)

Q: 为什么我新建的文章在浏览器里看不见？
- 检查文章头部的 draft 是不是 true。
- 检查文章头部的 date 是不是未来的时间。
- 如果你没运行 hugo server -D，请加上 -D 试试。
Q: 修改了主题配置，但是没生效？
- 有时候是浏览器缓存。试试在浏览器按下 Ctrl + F5 强制刷新。
- 如果是 Hugo 缓存，可以尝试删除 resources/ 文件夹后重新运行。
Q: 怎么更换主题？
- 主题放在 themes/ 文件夹。
- 在 hugo.toml 中修改 theme = "你的主题文件夹名称"。

5. 目录结构速查

content/：存放你的 Markdown 文章源码。
static/：存放图片、PDF、图标等原始资源，生成后会直接复制到根目录。
themes/：存放下载的主题。
public/：生成的成品网站（不要手动改这里面的代码）。
hugo.toml / config.toml：整个网站的“大脑”，改名字、改域名都在这里。

✍️ 每日更新流水账：

cd 进入目录
hugo new posts/xxx.md 或直接拖入 md 文件
hugo server -D 预览效果
满意后，运行 hugo 编译
将 public/ 部署到服务器

补充建议：

如果你以后还是觉得记命令麻烦，可以在你的项目根目录下新建一个叫 deploy.sh 的脚本文件，内容如下：

4.7 KiB Raw Blame History Unescape Escape