本文总结了通过 Halo 2.x REST API 发布文章的完整流程,包含踩过的坑和解决方案。
前置条件
- 已部署的 Halo 2.x 博客
- 在 个人中心 → 个人令牌 中创建 PAT(Personal Access Token)
- 认证方式:
Authorization: Bearer <your_token>
核心端点
基础路径:http://<your-halo-domain>
| 操作 | 方法 | 端点 |
|---|---|---|
| 获取文章列表 | GET | /apis/api.console.halo.run/v1alpha1/posts |
| 创建草稿 | POST | /apis/api.console.halo.run/v1alpha1/posts |
| 写入内容 | PUT | /apis/api.console.halo.run/v1alpha1/posts/{name}/content |
| 发布文章 | PUT | /apis/api.console.halo.run/v1alpha1/posts/{name}/publish |
| 获取文章内容 | GET | /apis/api.console.halo.run/v1alpha1/posts/{name}/head-content |
完整三步流程
第一步:创建草稿
POST /apis/api.console.halo.run/v1alpha1/posts
请求体示例:
{
"post": {
"apiVersion": "content.halo.run/v1alpha1",
"kind": "Post",
"spec": {
"title": "文章标题",
"slug": "article-url-slug",
"owner": "your-username",
"cover": "",
"deleted": false,
"excerpt": { "autoGenerate": true, "raw": "" },
"allowComment": true,
"pinned": false,
"priority": 0,
"publish": false,
"visible": "PUBLIC",
"categories": [],
"tags": [],
"htmlMetas": []
},
"metadata": {
"name": "",
"generateName": "post-",
"annotations": {}
}
},
"content": {
"raw": "placeholder",
"content": "placeholder",
"rawType": "markdown"
}
}
踩坑记录:
- ❌ 缺少
deleted字段会报错:Field 'deleted' is required - ✅ 必须包含
"deleted": false publish: false表示创建草稿
第二步:写入内容
PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/content
请求体示例:
{
"raw": "# 标题\n\nMarkdown 正文内容...",
"content": "<h1>标题</h1><p>HTML 正文内容...</p>",
"rawType": "markdown"
}
踩坑记录:
- ❌ 只提供
raw不提供content→ 页面空白,只有标题 - ✅ 必须同时提供
raw(Markdown源码)和content(HTML渲染结果) - 如果用脚本,需要自己将 Markdown 转为 HTML
第三步:发布文章
PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/publish
无需请求体,直接调用即可。
踩坑记录:
- ❌ 修改内容后不重新发布 → 页面显示旧内容
- ✅ 每次修改内容后都要重新调用 publish
- API 返回中
headSnapshot和releaseSnapshot一致才表示内容已同步
PowerShell 快速示例
$token = "your_pat_token"
$headers = @{
"Authorization" = "Bearer $token"
"Content-Type" = "application/json"
}
$baseUrl = "http://your-halo:8090"
# 1. 创建草稿
$createBody = @{ post = @{...}; content = @{...} } | ConvertTo-Json -Depth 10
$post = Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts" `
-Method POST -Headers $headers -Body $createBody
# 2. 写入内容
$contentBody = @{
raw = "# Hello"
content = "<h1>Hello</h1>"
rawType = "markdown"
} | ConvertTo-Json
Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts/$($post.metadata.name)/content" `
-Method PUT -Headers $headers -Body $contentBody
# 3. 发布
Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts/$($post.metadata.name)/publish" `
-Method PUT -Headers $headers
常见问题
| 问题 | 原因 | 解决 |
|---|---|---|
| 404 Not Found | 端点路径错误 | 使用 /apis/ 开头,不是 /api/ |
| 页面只有标题 | 缺少 HTML content | 同时提供 raw 和 content |
| 内容没更新 | 未重新发布 | 修改后再次调用 publish |
| 连接被拒绝 | curl 使用了代理 | 加 --noproxy "*" 参数 |
总结
记住三步口诀:创建 → 写内容 → 发布
每次改内容都要重新发布!希望这篇踩坑总结能帮到你 🎉