3.1 鉴权：每个请求都要过口令#

口令存环境变量 PUBLISH_TOKEN，前端登录成功后把口令放在请求头 x-publish-token 里带上，服务端逐次校验。比较要用常数时间函数，避免时序侧信道：

1
import crypto from "node:crypto";
2

3
export function safeEqual(a, b) {
4
  const ab = Buffer.from(String(a ?? ""), "utf8");
5
  const bb = Buffer.from(String(b ?? ""), "utf8");
6
  if (ab.length !== bb.length) return false;
7
  return crypto.timingSafeEqual(ab, bb);
8
}
9

10
// 每个端点的第一段逻辑
11
const publishToken = process.env.PUBLISH_TOKEN;
12
if (!safeEqual(req.headers["x-publish-token"], publishToken)) {
13
  res.statusCode = 401;
14
  res.end(JSON.stringify({ ok: false, error: "口令错误" }));
15
  return;
16
}

会话策略用 sessionStorage（存标签页内存，关浏览器即失效）而不是 localStorage，就实现了”每次打开发布台都要登录”。

3.2 发布端点：命名、frontmatter、提交三件事#

发布端点收到 { type, title, content, ...可选字段 } 后做三件事：

① 自动命名——这是”文件名序号”类博客的关键。发文章前先调 GitHub Contents API 列目录，正则抓所有 数字+文章.md 取最大值 +1：

1
const res = await fetch(
2
  `https://api.github.com/repos/${REPO}/contents/src/content/posts/txt?ref=${BRANCH}`,
3
  { headers: { Authorization: `Bearer ${token}` } },
4
);
5
const entries = await res.json();
6
let max = 0;
7
for (const e of entries) {
8
  const m = /^(\d+)文章\.md$/.exec(e.name);
9
  if (m) max = Math.max(max, Number(m[1]));
10
}
11
const path = `src/content/posts/txt/${max + 1}文章.md`;

更新公告按日期命名（更新公告20261003.md）、动态按时间戳命名（20261003-1217.md），同名冲突就追加 -2 后缀。命名规则永远现场查仓库算，不要缓存，这样本地手动加了文件它也不会撞车。

② 拼 frontmatter——两条容易翻车的经验：

• 字符串一律用 JSON.stringify 转义：标题里的引号、冒号、特殊字符，JSON.stringify 输出的就是合法 YAML 双引号字符串，手写拼接迟早被一个带 : 的标题弄炸
• 日期裸写、不要引号：published: 2026-10-03 会被 YAML 解析成 Date 对象（Zod schema 的 z.date() 才认）；写成 published: "2026-10-03" 就成了字符串，构建直接报 schema 错误

1
const lines = ["---", `title: ${JSON.stringify(title)}`, `published: ${now.date}`];
2
// 约定"留空不写"：可选字段没填就完全不出现在 frontmatter 里
3
if (fields.tags.length) lines.push(`tags: ${JSON.stringify(fields.tags)}`);
4
if (fields.slug) lines.push(`slug: ${JSON.stringify(fields.slug)}`);
5
lines.push("---", "", content);

③ 提交到仓库——用 Contents API 的创建接口，内容 base64 后 PUT 到目标分支：

1
await fetch(`https://api.github.com/repos/${REPO}/contents/${path}`, {
2
  method: "PUT",
3
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
4
  body: JSON.stringify({
5
    message: `post: ${title}`,            // 提交信息，进 git 历史一眼能看懂
6
    content: Buffer.from(markdown, "utf8").toString("base64"),
7
    branch: "master",                     // 推到构建监听的分支
8
  }),
9
});

提交成功即返回”已提交，3~5 分钟后生效”——到这一步，剩下的事全交给博客既有的自动构建，发布台不需要知道构建是否存在、是否成功。

3.3 管理端点：读、存、删#

• 列表（articles.js）：调 Git Trees API（/git/trees/master?recursive=1）一次拿到全仓库文件树，过滤出内容目录的 .md；再并发拉各文件的 frontmatter 头部解析出标题/日期/草稿标记，拼成列表
• 读取（article.js GET）：Contents API 返回 base64 正文和 sha（文件指纹）
• 保存（PUT）：必须带上刚才读到的 sha，GitHub 据此判断文件有没有被别人动过——sha 对不上返回 409，提示”文件已被他人改动，请刷新重试”，两个人同时改稿就不会互相覆盖
• 删除（DELETE）：同样要 sha，删除即一次 commit，走同样的构建上线

三条铁律写在端点入口：

1
// ① 路径白名单：只允许内容目录的 markdown，防任意文件被改/删
2
function isSafeContentPath(p) {
3
  if (p.includes("..") || p.startsWith("/")) return false;
4
  return /^src\/content\/(posts|dynamic)\/.+\.(md|mdx)$/.test(p);
5
}
6
// ② 内容不能为空
7
// ③ sha 必须提供（先读后改，不允许盲写）

步骤 1：导入仓库，设 Root Directory#

Vercel → Add New Project → 导入你的博客仓库 → Settings → General → Root Directory 填 publisher（根目录）。不填的话 Vercel 会去构建整个博客本体，必错。

步骤 2：环境变量#

Settings → Environment Variables 加两条：

坑 ①：Command "build" not found#

Vercel 对 monorepo 会在仓库根装依赖（正常），但构建命令跑在 Root Directory 里——你的子目录 package.json 没有 build 脚本就报这个。修法：补一个空脚本 "build": "echo ok"（或对应包管理器的等价物）。

坑 ②：No Output Directory named "dist" found#

这个最阴险：仓库根遗留的 vercel.json（写着 buildCommand、outputDirectory: dist）会被套用到你的发布台项目上，而且 vercel.json 优先级高于界面设置，在界面上怎么改都没用。双保险修法（两头都堵死）：

• 子目录放自己的 vercel.json：{ "outputDirectory": "." }
• build 脚本顺便产出一份 dist/（mkdir -p dist && cp index.html dist/），满足根配置的 dist 预期

排查时先看报错信息里的配置来源指向哪，再决定动哪边的 vercel.json——别去改博客本体的根配置，那是博客自己的部署遗产。

步骤 3：部署#

点 Deploy（部署），等到 Ready（就绪）。

坑 ③：打开部署地址跳到 vercel.com/login#

新项目默认开着 Deployment Protection（部署保护）——Vercel 认证拦住了所有访客。到 Settings → Deployment Protection → Vercel Authentication（Vercel 身份验证）关掉（或只留预览环境保护）。发布台自己有口令把关，页面加 noindex 即可放心公开。

步骤 4：绑定自有子域名#

坑 ④：*.vercel.app 在国内被 DNS 污染，不绑域名基本打不开。

1. Settings → Domains → Add Existing（添加已有域名）→ 输入你的子域名（如 pub.example.com）
2. 到 DNS 服务商（如 Cloudflare）加一条 CNAME：名称填子域，值照 Vercel 显示的填
3. 建议开启 CDN 代理（橙云）——解析走代理边缘，避开污染

坑 ⑤：配完 Vercel 会报 Proxy Detected（检测到代理）警告——可以无视。它只是抱怨自己的防护工具在代理后面不好使，对口令保护的个人发布页毫无影响，而代理恰恰是国内能稳定访问的关键。

步骤 5：验证#

打开你的子域名 → 登录 → 发一条测试内容 → 确认：仓库出现新 commit → 自动构建触发 → 博客页面出现这条内容。三环都绿，系统就通了。