# 操作指南

这个博客的日常操作：写文章、写偶得、加照片、本地预览、部署上线。

---

## 0. 首次准备

```bash
cd /home/tianxuetao/文档/VermilionVoid-main
pnpm install          # 只需在第一次、或依赖变动后执行
```

平时不需要重复装依赖。

---

## 1. 本地预览（写得最多的一步）

```bash
pnpm dev
```

打开 **http://localhost:4321**。改任何文件浏览器会自动刷新，不用重启。

停止：在终端按 `Ctrl + C`。

> 端口被占用时 Astro 会自动换到 4322、4323……看终端输出的那行 `Local` 网址即可。

---

## 2. 写一篇正式文章

### 建文件

```bash
pnpm new-post "树莓派装 Docker 全程记录" --category 教程 --tags Docker,树莓派
```

常用选项：

| 选项 | 作用 |
|---|---|
| `--category 教程` | 分类，同时决定放进哪个子目录 |
| `--tags Docker,树莓派` | 标签，逗号分隔 |
| `--description "摘要"` | 摘要，用于 SEO 和列表卡片 |
| `--image /assets/images/xxx.webp` | 封面图 |
| `--file my-slug` | 自定义文件名（默认用标题） |
| `--pinned` | 置顶 |
| `--draft` | 草稿，构建时不会输出 |

生成的文件长这样：

```yaml
---
title: "树莓派装 Docker 全程记录"
published: 2026-09-14
description: "摘要"
tags:
  - "Docker"
  - "树莓派"
category: "教程"
---
```

### 写正文

直接在 `---` 下面往下写 Markdown。支持：

- 标题、列表、表格、引用、代码块（带行号和复制按钮）
- 数学公式：`$行内$` 和 `$$独立成段$$`
- 提示框：

  ```markdown
  > [!NOTE]
  > 这是一条提示。也可以用 TIP / IMPORTANT / CAUTION / WARNING
  ```

- 图片：`![说明](/assets/images/图片.webp)`

### 不想用脚本

手动在 `src/content/posts/` 下建 `.md` 文件也可以，**只有 `title` 和 `published` 是必填的**，其余字段都能省略。

### 加密文章（可选）

```yaml
encrypted: true
password: "你的密码"
```

正文会被加密，需要输密码才能阅读。

---

## 3. 写一条「偶得」

```bash
pnpm new-thought "换了散热，温度降了 15 度。" --location 张掖 --tags 硬件
```

| 选项 | 作用 |
|---|---|
| `--title` | 可选标题 |
| `--location` | 地点，显示在日期旁 |
| `--weather` | 天气 |
| `--images a.png,b.png` | 配图，逗号分隔 |
| `--tags 生活,硬件` | 标签 |
| `--pinned` | 置顶 |

> ⚠️ **`published` 一定要带时区**（脚本会自动写成 `2026-09-14T12:36:47.215Z`）。
> 手写成不带时区的 `2026-09-14 12:36`，YAML 会按 UTC 解析，**显示的日期会差一天**。

偶得页有两种模式：**专注**（一次一条，←/→ 切换）和**时间线**（按年份分组 + 标签筛选）。

---

## 4. 加照片到相册

照片放在 `public/gallery/<相册id>/`，**构建时自动扫描目录**，不用在配置里逐个登记。

加一个新相册 = 两步：

1. 建目录并放照片：`public/gallery/我的相册/`
2. 在 `src/data/gallery.ts` 的 `albums` 里加一项：

```ts
{
  id: "我的相册",              // 必须和目录名一致
  name: "相册显示名",
  description: "一句话描述",
  location: "甘肃-张掖",       // 可选
  date: "2026-09-14",         // 可选
  tags: ["旅行"],              // 可选，用于索引页筛选
}
```

封面优先级：`cover` 字段 > 目录里的 `cover.*` 文件 > 第一张图。

> 📏 **放进去之前先压图。** `public/` 下的资源由服务器原样下发，**不经过 Astro 优化**。
> 一张 4K 原图可能十几 MB，会让页面加载非常慢。建议先压成 WebP 再放。

---

## 5. 检查与构建

```bash
pnpm check      # 类型 + 内容校验，frontmatter 写错会在这里报出来
pnpm build      # 构建到 dist/，并建立搜索索引
pnpm preview    # 本地预览构建产物（搜索功能只有这里才生效）
```

写完一篇后建议跑一次 `pnpm check`，能提前发现 frontmatter 字段写错。

---

## 6. 部署上线

```bash
./deploy.sh
```

它会构建一次，然后 rsync 到树莓派和云服务器，覆盖生产前会问你一句确认。

| 命令 | 用途 |
|---|---|
| `./deploy.sh` | 构建 + 部署两个目标 |
| `./deploy.sh -y` | 同上，跳过确认（适合脚本） |
| `./deploy.sh --pi-only` | 只推树莓派，先在内网看效果 |
| `./deploy.sh --cloud-only` | 只推云服务器（正式上线） |
| `./deploy.sh --dry-run` | 空跑，只显示会同步哪些文件 |
| `./deploy.sh --skip-build` | 不重新构建，直接推现有 `dist/` |

推荐节奏：先 `--pi-only` 在树莓派上确认没问题，再 `--cloud-only` 上生产。

> 目标地址和 SSH 密钥在 `deploy.sh` 顶部的**配置区**。
> 脚本在构建失败或产物异常时会**直接中止**——因为推送用的是 `rsync --delete`，
> 拿一个残缺的 `dist/` 上去会清空线上目录。

---

## 7. 改站点信息

日常最常改的三个文件：

| 想改什么 | 改哪里 |
|---|---|
| 站名、域名、描述、主题色、统计 | `src/data/site.ts` |
| 昵称、签名、头像、GitHub/邮箱 | `src/data/profile.ts` |
| 首页打字机文案 | `src/components/hero.tsx` 顶部的 `phrases` |

主题色只改 `site.ts` 里的 `themeHue` 一个数字：`0` 红、`25` 朱红（当前）、`200` 青、`250` 蓝绿、`345` 粉。

---

## 8. 常见问题

**改了文件但浏览器没变**
先手动刷新。若仍无效，`Ctrl + C` 停掉再 `pnpm dev` 重启。

**构建时报 `ENOSPC: System limit for number of file watchers reached`**
系统的 inotify 监视器配额用完了，不是代码问题。页面照常访问，但热更新可能失效。
彻底解决需要放宽内核参数（要 sudo）：

```bash
sudo sysctl fs.inotify.max_user_watches=524288
```

**偶得的日期差一天**
看第 3 节：`published` 必须带时区。

**图片不显示**
检查路径是否以 `/` 开头（`/assets/images/x.webp`），以及文件是否真在 `public/` 下对应位置。
注意 `public/` 里的文件路径就是 URL 路径，**没有 `public` 这一段**。

**想回退到之前的状态**

```bash
git log --oneline        # 看提交
git reset --hard <提交号>
```

---

## 附：目录速查

```
src/content/posts/       文章（按分类分子目录）
src/content/thoughts/    偶得
src/content/studies/     专题（目前为空）
src/data/site.ts         站点配置
src/data/profile.ts      个人信息
src/data/gallery.ts      相册配置
src/data/comments.ts     评论配置
src/components/hero.tsx  首页打字机文案
public/assets/images/    文章配图
public/gallery/          相册照片
scripts/                 辅助脚本
dist/                    构建产物（gitignore）
```