Jeff 个人站发布教程

从零开始，教你发布博客和集锦

零、你需要知道的

个人站有两样东西：

• 博客：一篇文章一个 .md 文件，放在 src/data/post/ 目录
• 集锦：首页的卡片，点击后列出某个主题的所有博客文章

改完文件后，在服务器上跑一条命令就发布：

cd /opt/jeff-site && docker compose build --no-cache && docker compose up -d && docker system prune -f

💡 把这条命令存好，每次改完内容都要跑一遍，等 2 分钟刷新网站就能看到效果。

一、发布一篇博客

1.1 创建文章文件

在服务器上创建文件：/opt/jeff-site/src/src/data/post/文章名.md

文件名建议用英文+连字符，比如 my-first-post.md。

1.2 文章模板（直接复制改）

---
title: 文章标题
excerpt: 简短摘要，会显示在博客列表里
category: 分类名
tags:
  - 标签1
  - 标签2
image: https://images.unsplash.com/photo-xxxxx?参数
publishDate: 2026-07-28
author: Jeff
---

## 第一个小标题

正文内容，支持 **加粗** 和 *斜体*。

### 第二个小标题

- 列表项 1
- 列表项 2

> 引用文字

⚠️ --- 之间的部分是文章信息，必须放在文件最开头。title 和 image 必填。

1.3 各字段说明

💡 排序规则： 文章按 publishDate 降序排列（最新在前）。如果多篇文章同一天发布，只写日期无法区分先后，会按文件名字母排序。想让某篇排到最前面，加具体时间即可：publishDate: 2026-07-28T23:00:00（时间越晚排越前）。 | author | ❌ | 作者 | Jeff |

1.4 tags 怎么填

tags 是集锦和博客之间的桥梁。一篇文章打了 ai-tools 标签，就会自动出现在「AI 工具合集」集锦里。

标签名建议用英文小写+连字符（如 ai-tools），避免中文 URL 编码问题。

二、添加图片

方案 A：Unsplash 外链（推荐，零配置）

1. 打开 unsplash.com，搜关键词找到喜欢的图
2. 右键图片 → 复制图片地址
3. 在链接末尾加上参数：?ixlib=rb-4.0.3&auto=format&fit=crop&w=900&h=506&q=80
4. 粘贴到 image: 后面

💡 封面图尺寸建议： 博客封面图和集锦封面图统一使用 900×506（16:9 裁剪），在 Unsplash 链接里加 &w=900&h=506&fit=crop 参数即可。这样首页博客卡片和集锦卡片的图片尺寸完全一致，排版整齐。

常用搜索词速查：

方案 B：用自己的图

1. 把图片传到 /opt/jeff-site/src/src/assets/images/
2. 引用：/_astro/图片文件名

Astro 构建时会自动压缩优化。

三、文章正文怎么写

支持标准 Markdown 格式：## 标题、**加粗**、*斜体*、列表、引用、![图片](/_astro/xxx.jpg)、[链接](url)。

四、集锦：把博客按主题归类

原理

博客文章（tags: [ai-tools]）
        ↓ 自动关联
集锦卡片 → 点击 → 列出所有 ai-tools 标签的文章

添加新集锦

编辑 /opt/jeff-site/src/src/data/collections.json：

{
  "title": "集锦标题",
  "description": "简短描述",
  "image": "https://images.unsplash.com/photo-xxxxx?...",
  "link": "/tag/标签名",
  "linkExternal": false
}

⚠️ JSON 逗号规则（新手必看）：

[
  { "title": "第一个" },   ← 有逗号
  { "title": "第二个" },   ← 有逗号
  { "title": "最后一个" }  ← 最后一个不加逗号
]

最后一项后面不能有逗号，其余每项后面必须有逗号。逗号漏了或多加了都会导致构建失败。

完整示例

创建「读书笔记」集锦：

1. collections.json 加一条，link: "/tag/reading"
2. 博客文章 tags 里加 reading
3. 跑部署命令

五、发布流程总结

① 写文章 .md → 放到 src/data/post/
② 如果是新主题 → 在 collections.json 加集锦
③ 跑部署命令 → 等 2 分钟 → 刷新网站

部署命令

cd /opt/jeff-site && docker compose build --no-cache && docker compose up -d && docker system prune -f

六、常见问题

• 改完没效果？ 确认跑了部署命令，等够 2 分钟，Ctrl+F5 强制刷新
• 集锦卡片点进去空的？ 检查 tags 和 link 标签名是否一致
• 想删文章？ 删掉 .md 文件，跑部署命令
• Unsplash 图慢？ 下载放到 src/assets/images/ 改本地方案
• 构建报错 Failed to parse JSON？ 检查 collections.json 的逗号：最后一项不能有逗号，其余每项必须有逗号

相关链接

• 网站源码：/opt/jeff-site/src/
• 部署命令：cd /opt/jeff-site && docker compose build --no-cache && docker compose up -d && docker system prune -f
• [[Jeff-个人站技术架构]]