博客跑在 Halo 上,一直有个偷懒的想法:写完 Markdown 直接推上去,不用再打开后台编辑器粘贴一遍。这周把这个念头落地了,中间撞了三个坑,每个坑都不复杂,但都能让人对着 500 发呆半小时。记一下。
一、Halo 的两套 API
Halo 2.x 的 API 分成几组,接入前先分清:
content.halo.run/v1alpha1—— 资源本身,Post / Category / Tag 的标准 CRUD,返回裸对象。api.console.halo.run/v1alpha1—— 控制台的行为,建草稿、发布、撤回,返回的是包装对象。- 认证用「个人中心 → 个人令牌」创建的 PAT,请求头
Authorization: Bearer pat_xxx。2.26 的令牌是一串pat_开头的 JWT,将近一千个字符,别被长度吓到。
这里先埋一个坑:两套 API 返回的结构不一样。比如列文章:
{
"page": 1, "size": 20, "total": 1,
"items": [
{ "post": { … }, "stats": { … }, "owner": { … }, "categories": [], "tags": [] }
]
}
文章本体在 items[].post 里,不在 items[] 上。第一版脚本就是在这里报的 Cannot read properties of undefined。
二、坑一:建草稿不能直接发 Post
直觉是 POST 一个 Post 对象过去。照着 v1alpha1 的 schema 拼:
{
"apiVersion": "content.halo.run/v1alpha1",
"kind": "Post",
"spec": { "title": "测试", "slug": "test" }
}
返回 500,日志里是:
java.lang.NullPointerException: Cannot invoke "run.halo.app.core.extension.content.Post.getSpec()" because "post" is null
一个经典的 Java NPE,看得人一头雾水:我明明传了 post 啊。
翻 issue 才发现这是个老问题(2.24 就有人问过),回答是 body 结构不对,要按 DraftPost 的 schema 来。真正的结构是外面再包一层:
{
"post": {
"apiVersion": "content.halo.run/v1alpha1",
"kind": "Post",
"metadata": { "generateName": "post-" },
"spec": { "title": "…", "slug": "…" }
},
"content": {
"raw": "# 标题\n\n正文",
"content": "<h1>标题</h1>\n<p>正文</p>",
"rawType": "markdown"
}
}
一个 PostRequest,包着「文章元数据」和「正文」两样东西。 post 为 null 时 NPE 就是这么来的——服务端在解包。
三、坑二:Markdown 得自己渲染
content 里有 raw 和 content 两个字段,看名字像是「原文 + 渲染结果」。我以为只给 raw 就行,服务端会补渲染。
实测拿 head-content 回来对比:raw 是我传的 Markdown,content 是我随手写的 HTML,一个字节都没动。
Halo 是 headless 架构,渲染在编辑器侧完成。所以想让页面正常显示,必须自己把 Markdown 转成 HTML——本地用 marked 就够了:
const html = marked.parse(markdown, { gfm: true });
这一步偷懒的后果很隐蔽:后台编辑器里看文章是好的(它拿 raw 重新渲染),但发布出去的页面是空白的。
四、坑三:环境变量在,但读不到
PAT 放在 Windows 用户环境变量 HALO_TOKEN 里。脚本里 process.env.HALO_TOKEN 一读,空的——因为 agent 进程启动早于设置变量。
退一步,让 node 自己调 PowerShell 去取:
execFileSync('powershell.exe', [
'-Command',
'[Environment]::GetEnvironmentVariable("HALO_TOKEN","User")'
]);
直接 EPERM。沙箱不允许 node 起子进程(管道被拦),但同样的命令在 bash 里是通的。
最后的解法是加一层 shell 包装:由 bash 读环境变量、注入进程环境,再 exec node。多一个 halo.sh,问题消失。令牌从头到尾只活在内存和注册表里,没落过盘。
五、流水线
工具跑起来是这样:
./halo.sh post article.md \
--categories "技术" \
--tags "Halo,API" \
--publish
内部五步:读 Markdown → 渲染 HTML → 解析分类和标签(不存在的自动建)→ POST 建草稿 → 可选发布。
发布接口要带快照名:
PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/publish
{ "headSnapshotName": "4bc2e2d3-…" }
这个名字在草稿返回体的 spec.headSnapshot 里,别自己编。
另外删除走的是 DELETE /apis/content.halo.run/v1alpha1/posts/{name}。console 组同名端点返回 404,我第一次删测试文章删了个寂寞。
六、验证
一次端到端:建草稿 → 发布 → curl 前台页面 grep 到正文 → 撤回 → 删除。五步全 200,页面里能搜到刚写的那句话,才算真通了。
顺手把测试过程留下的分类、标签、文章都清干净,站点回到原样。
尾声
现在写文章的流程变成了:丢一个主题过去,十分钟后草稿躺在后台,预览链接直接可点,确认没问题再点发布。
顺便说一句,这篇也是这么发出来的。