Files

T

- scripts/new-post.mjs + pnpm new-post：按标题建文章，支持 --category/--tags/
  --description/--image/--file/--pinned/--draft，标题里的冒号引号会正确转义
- docs/操作指南.md：写文章、发偶得、加相册、预览、检查、部署的完整流程
- 修复 astro check 报出的 2 个类型错误（gallery 索引页 querySelector 未指定
  HTMLElement，导致 dataset 不可用）。现在 pnpm check 为 0 error

2026-09-14 20:50:22 +08:00

6.6 KiB

Raw Blame History

操作指南

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

0. 首次准备

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

平时不需要重复装依赖。

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

pnpm dev

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

停止：在终端按 Ctrl + C。

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

2. 写一篇正式文章

建文件

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

常用选项：

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

生成的文件长这样：

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

写正文

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

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

提示框：

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

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

不想用脚本

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

加密文章（可选）

encrypted: true
password: "你的密码"

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

3. 写一条「偶得」

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>/，构建时自动扫描目录，不用在配置里逐个登记。

加一个新相册 = 两步：

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

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

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

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

5. 检查与构建

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

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

6. 部署上线

./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）：

sudo sysctl fs.inotify.max_user_watches=524288

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

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

想回退到之前的状态

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）

6.6 KiB Raw Blame History Unescape Escape