121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
|
||
# 🚀 我的 Hugo 博客操作手册
|
||
|
||
这份文档是为了防止我忘记 Hugo 指令而准备的“防呆”指南。
|
||
|
||
---
|
||
|
||
## 1. 常用开发指令 (本地电脑)
|
||
|
||
在进行任何操作前，请先进入博客的根目录（即本文件所在的文件夹）。
|
||
|
||
### 🛠️ 启动本地预览（最常用）
|
||
```bash
|
||
hugo server -D
|
||
```
|
||
* **作用**：在本地运行一个实时预览服务器。
|
||
* **参数 `-D`**：表示显示标记为 `draft: true`（草稿）的文章。
|
||
* **查看地址**：在浏览器输入 `http://localhost:1313/`。
|
||
* **注意**：这个命令是动态的，你修改并保存 Markdown 文件后，浏览器会自动刷新。
|
||
|
||
### 📝 新建一篇文章
|
||
```bash
|
||
hugo new posts/我的第一篇博客.md
|
||
```
|
||
* **作用**：在 `content/posts/` 目录下创建一个新的 Markdown 文件，并带上基础的模板（元数据）。
|
||
* **建议**：文件名尽量不要有空格，可以使用中划线，如 `my-first-post.md`。
|
||
|
||
### 🏗️ 生成静态 HTML 文件
|
||
```bash
|
||
hugo
|
||
```
|
||
* **作用**：将你的所有 Markdown 源码正式编译成 HTML/CSS/JS。
|
||
* **产出**：所有的静态文件都会生成在根目录下的 `public/` 文件夹中。
|
||
* **场景**：当你准备把网站更新到服务器上时，才运行这个命令。
|
||
|
||
---
|
||
|
||
## 2. 关于“写文章”的说明
|
||
|
||
### 💡 我可以直接把写好的 .md 挪进来吗？
|
||
**可以！** 你不需要非得用 `hugo new` 指令。你可以直接把写好的 Markdown 文件直接拖进 `content/posts/` 目录下。
|
||
|
||
**但是（非常重要）：**
|
||
Hugo 识别文章是靠 Markdown 文件头部的 **Front Matter**（元数据）。如果你直接挪文件，请务必在文章最顶部加上这段代码（以 YAML 格式为例）：
|
||
|
||
```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` 文件夹
|
||
这是最简单的方式。
|
||
1. 本地运行 `hugo`。
|
||
2. 使用 FTP/SCP/Rsync 将本地生成的 `public/` 文件夹里的所有内容发到 Linux 服务器的 Web 目录（如 `/var/www/html`）。
|
||
3. **优势**：服务器不需要安装 Hugo。
|
||
|
||
### 场景 B：在服务器上通过源码生成
|
||
如果你在服务器上也安装了 Hugo，并且通过 Git 同步代码：
|
||
1. 在服务器执行 `git pull` 同步源码。
|
||
2. 在服务器执行 `hugo`（不需要带 server）。
|
||
3. 确保你的 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`：整个网站的“大脑”，改名字、改域名都在这里。
|
||
|
||
---
|
||
|
||
### ✍️ 每日更新流水账：
|
||
1. `cd` 进入目录
|
||
2. `hugo new posts/xxx.md` 或 直接拖入 md 文件
|
||
3. `hugo server -D` 预览效果
|
||
4. 满意后，运行 `hugo` 编译
|
||
5. 将 `public/` 部署到服务器
|
||
|
||
---
|
||
|
||
### 补充建议：
|
||
如果你以后还是觉得记命令麻烦，可以在你的项目根目录下新建一个叫 `deploy.sh` 的脚本文件，内容如下：
|
||
|