TimeHostel 博客发布使用文档 ​

这篇文章是 TimeHostel 博客项目的写作与发布使用说明。

目标：新人第一次接触仓库，也能在 10 分钟内完成本地预览、写一篇文章并通过 Git 推送触发 Vercel 自动部署上线。

仓库地址：https://github.com/libaxuan/TimeHostel线上站点：https://blog.autoais.eu.org技术栈：VitePress 1.2 + Vue 3 + Vercel 文章目录：posts/<年份>/*.md本地预览：npm run dev（默认端口 9877） 部署方式：Git 推送触发 Vercel 自动构建 / 可选 Vercel CLI 手动部署

一、项目约定（先读这个，后面就不会踩坑） ​

1. 文章文件放哪里 ​

必须放在 posts/<年份>/ 目录下，例如：

posts/2026/0318-publish-guide.md

构建时 VitePress 会扫描 posts/**/*.md 并用 gray-matter 解析 front-matter，自动生成：

• 首页/列表（按 date 降序排列）
• 标签页（按 tags）
• 分类页（按 categories）
• 归档页（按 date 的年份分组）

2. front-matter 字段规范 ​

每篇文章顶部必须包含以下字段（缺字段可能导致页面渲染异常）：

---
title: 文章标题
tags: [标签1, 标签2]
categories: [技术共享]
date: 2026-03-18 10:30:00
description: 15字左右的短描述
articleGPT: 150字左右的AI摘要
---

必填字段说明 ​

可选字段 ​

3. 分类（categories）有效范围 ​

目前站点使用以下 5 个分类，请严格从中选取，不要自创新分类（否则会生成无内容的分类页）：

其它内容细分请放到 tags 里（标签没有数量限制）。

4. 标签（tags）注意事项 ​

• 纯英文标签会被自动转为小写（例如 Flux → flux、VitePress → vitepress），这是为了避免大小写不一致导致 Linux 环境构建失败。
• 含中文的标签保持原样（例如 AI绘画、崩塌与重建）。
• 写 tags 时不需要自己手动转小写，构建会自动处理。

5. 文件名怎么取 ​

两种方式，选一个坚持用：

重要：项目开启了 cleanUrls: true，文章 URL 不带 .html 后缀。例如：https://blog.autoais.eu.org/posts/2026/0318-publish-guide。一旦发布后不要随意改文件名，否则旧链接会失效。

6. 文章底部推广块 ​

已做成统一组件，默认在所有文章页底部自动显示，正文里不需要手动粘贴。如果某篇文章不想显示，在 front-matter 加 promo: false。

二、Mac 本地写作 + 预览（最常用流程） ​

步骤 1：安装 Node.js（>= 18） ​

推荐用 nvm / fnm / brew / 官网安装。验证：

node -v   # 需要 >= 18
npm -v

步骤 2：克隆仓库并安装依赖 ​

git clone https://github.com/libaxuan/TimeHostel.git
cd TimeHostel
npm install

步骤 3：启动本地预览（实时热更新） ​

npm run dev

浏览器访问：http://localhost:9877/

修改/新增 .md 文件后页面会自动刷新（HMR）。

步骤 4：新建文章 ​

方式 A：用脚本创建（推荐） ​

npm run new-post

按提示依次输入：文章标题、文章描述、标签（逗号分隔）、分类（逗号分隔）。

脚本会自动：

• 读取 .vitepress/theme/templates/post-template.md 模板
• 填入当前时间（精确到秒）
• 生成文件到 posts/<年份>/<YYYY-MM-DD>-<slug>.md

注意：如果标题是纯中文，slug 生成器会把中文字符去掉，可能产生空 slug。这种情况下建议手动把文件重命名为 MMDD-你想要的英文slug.md。

方式 B：手动创建 ​

在 posts/<年份>/ 下新建 .md 文件，把上面第 2 节的 front-matter 模板复制进去，补上正文即可。

步骤 5：本地构建检查（发布前建议跑一次） ​

npm run build

构建成功说明线上 Vercel 构建大概率也能通过。如果想本地预览构建后的静态站点：

npm run preview

三、Ubuntu 服务器环境搭建（远程写作 / CI 构建） ​

以 Ubuntu 22.04+ 为例。适用于 VSCode Remote-SSH 远程写作或服务器端构建验证。

步骤 1：安装基础工具 ​

sudo apt update
sudo apt install -y git curl

步骤 2：安装 Node.js（推荐 nvm） ​

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install 18
nvm use 18
node -v
npm -v

步骤 3：配置 Git SSH（如果要推送代码） ​

ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub

把输出的公钥添加到 GitHub → Settings → SSH and GPG keys。

验证连接：

ssh -T git@github.com

步骤 4：克隆仓库、安装依赖、构建 ​

git clone git@github.com:libaxuan/TimeHostel.git
cd TimeHostel
npm install
npm run build

步骤 5：服务器上预览（可选） ​

npm run dev

package.json 里带了 --host 参数，会监听所有网卡（0.0.0.0:9877），注意：

• 需要在安全组/防火墙中开放 9877 端口
• 不建议在生产环境长期暴露 dev 服务，仅用于临时排查

四、Git 推送发布（推荐：触发 Vercel 自动部署） ​

这是最推荐的上线方式：push 到 main 分支 → Vercel 自动构建 → 自动发布。

步骤 1：确认分支 ​

git branch    # 确认当前在 main
git status    # 查看改动

步骤 2：写文章或修改内容 ​

在 posts/<年份>/ 下新增/修改文章即可。

步骤 3：提交并推送 ​

# 只提交文章（最常见场景）
git add posts/
git commit -m "post: 文章简要说明"
git push

# 如果同时修改了配置/组件/脚本，用 git add .
git add .
git commit -m "feat: 改动说明"
git push

步骤 4：查看部署结果 ​

进入 Vercel 项目面板，查看最新一次 Deployment：

五、Vercel CLI 手动部署（可选） ​

适用于：不想等 Git 自动部署、临时测试、或在非 Git 环境部署。

步骤 1：安装 CLI 并登录 ​

npm i -g vercel
vercel login

步骤 2：部署 ​

cd TimeHostel

# Preview 部署（生成预览 URL，不影响生产）
vercel

# 生产部署（直接更新线上站点）
vercel --prod

仓库里也提供了脚本 npm run deploy:vercel，本质是 vercel deploy（Preview 部署）。如果要推到生产，请直接用 vercel --prod。

首次运行 vercel 会让你选择/绑定 Vercel Project，按提示操作即可。

六、常见问题排查 ​

1）categories/tags 写错导致分类/标签页异常 ​

# ✅ 正确
categories: [技术共享]
tags: [VitePress, 博客]

# ❌ 错误：不是数组
categories: 技术共享
tags: VitePress

2）构建失败：Node 版本太低 ​

node -v   # 必须 >= 18

3）构建失败：标签大小写问题 ​

英文标签在构建时会被自动转为小写。如果你在文章里写了 Flux，标签页 URL 会是 /pages/tags/flux（而不是 /pages/tags/Flux）。这是正常行为，目的是避免 Linux 环境下大小写敏感导致的构建错误。

4）npm run new-post 中文标题生成空文件名 ​

脚本的 slug 生成器会去掉非英文字符。如果标题是纯中文（如"龙虾养殖指南"），生成的文件名可能是 2026-03-18-.md。

解决：手动把文件重命名为有意义的名字，如 0318-lobster-guide.md。

5）新增文章后页面没更新 ​

• 本地：确认 npm run dev 仍在运行，强刷页面（Mac: Cmd+Shift+R）
• 线上：确认 git push 成功，到 Vercel 面板确认有新的 Deployment

6）端口被占用 ​

本地默认端口 9877。如果被占用：

# 查看占用进程
lsof -i :9877

# 或修改端口：.vitepress/config.mjs → vite.server.port

七、新人最短路径（TL;DR） ​

# 1. 克隆 & 安装
git clone https://github.com/libaxuan/TimeHostel.git
cd TimeHostel
npm install

# 2. 启动预览
npm run dev

# 3. 创建新文章
npm run new-post

# 4. 用编辑器写正文（保存即热更新）

# 5. 构建检查（可选但推荐）
npm run build

# 6. 推送发布
git add .
git commit -m "post: 新文章标题"
git push
# → Vercel 自动构建上线