Halo自定义API接口，对接小程序客户端
很多朋友用 Halo 搭建了博客，又想把它作为内容源接入自己的微信小程序，但 Halo 默认没有专门给小程序用的接口。
这篇教程就带你从零开始，在 Halo 里创建一个自定义 API 接口，并让小程序安全地拿到文章数据。
整个过程会涉及后台配置、权限设置和前端调用，每一步都有明确的操作路径和验证方法。
动手前需要确认的环境和权限
在开始写代码之前，先检查几个基础条件，能避免大部分低级错误。
- Halo 版本：建议使用 Halo 2.x，因为 2.x 提供了更完整的自定义端点（Custom Endpoint）功能。你可以在 Halo 后台的“关于”或“系统信息”里确认版本，如果版本较低，建议先升级。
- 管理员账号：你需要一个 Halo 管理员账号，用来创建 API 令牌和配置接口权限。
- 小程序开发者工具：安装微信开发者工具，并准备好小程序的 AppID 和 AppSecret。
- 服务器网络：确保小程序服务器可以访问你的 Halo 站点域名，如果 Halo 开启了 HTTPS，小程序也必须使用 HTTPS 请求。
在 Halo 后台创建自定义 API 接口
Halo 2.x 允许通过“自定义端点”功能暴露特定数据。
具体路径是：登录 Halo 后台 -> 左侧菜单找到“插件”或“设置” -> 进入“自定义端点”。
不同主题或版本可能略有差异，如果找不到，请先确认是否安装了官方提供的“自定义端点”插件。
创建接口时，你需要填写几个关键字段：
- 路径：例如
/apis/custom.mini-program.posts，这是小程序请求的地址后缀。 - 请求方法：选择
GET，因为小程序通常只读取数据。 - 权限：选择“公开”或“匿名访问”，否则小程序未登录时无法获取内容。
- 数据源：可以选择“文章列表”或自定义查询，并设置返回字段，比如
title、slug、cover、publishTime、content。
一个简单的接口配置片段大致如下（具体语法请以你 Halo 后台的提示为准）：
{
"path": "/apis/custom.mini-program.posts",
"method": "GET",
"permission": "anonymous",
"query": {
"page": 1,
"size": 10,
"sort": "publishTime,desc"
}
}保存后，Halo 会生成一个可访问的 URL。
你可以在浏览器里直接打开这个 URL，如果返回 JSON 格式的文章数据，说明接口已经生效。
小程序端如何安全地请求这个接口
拿到接口地址后，在小程序里发起网络请求。
微信小程序要求所有请求的域名必须在小程序后台的“开发设置”->“服务器域名”里配置为合法域名。
假设你的 Halo 站点是 https:，
//blog.yourdomain.com
接口路径是 /apis/custom.mini-program.posts，
那么在小程序 request 中的写法如下：
wx.request({
url: 'https://blog.yourdomain.com/apis/custom.mini-program.posts',
method: 'GET',
success(res) {
console.log(res.data);
// 将 res.data 渲染到页面
},
fail(err) {
console.error('请求失败', err);
}
});关键点：如果 Halo 接口需要认证，比如用了 Token，那么要在请求头里加上 Authorization。
但为了小程序安全，不建议把管理员 Token 放在前端，而是应该让 Halo 接口保持匿名只读，或者通过自己的后端中转。
避坑指南：常见报错与处理
对接过程中很容易遇到几个典型问题，提前了解能省不少时间。
- 403 Forbidden：说明接口权限没有设为匿名，或者小程序请求时缺少必要头信息。检查 Halo 自定义端点的权限设置。
- 404 Not Found：接口路径写错，或者 Halo 没有启用自定义端点插件。重新核对后台生成的完整 URL。
- 小程序提示“不在以下 request 合法域名列表中”：去微信公众平台 -> 开发 -> 开发设置 -> 服务器域名，把 Halo 域名添加进去，注意必须是 HTTPS。
- 返回数据为空：检查查询条件是否太严格，比如
status只选了“已发布”，但文章还是草稿状态。
如果遇到跨域问题，Halo 通常已经处理，但如果你用了 CDN 或反向代理，需要确保代理没有过滤掉 Access-Control-Allow-Origin 头。
验证接口是否真正可用
完成配置后，不要急着写复杂页面，先用最简单的方式验证。
- 在浏览器无痕模式下打开接口 URL，确认能看到 JSON 数据。
- 在小程序开发者工具的“网络”面板中查看请求状态码，200 表示成功。
- 在小程序页面的
onLoad里打印res.data，确认字段名和你预期的一致。 - 如果文章内容包含 HTML 标签，小程序里需要用
rich-text组件渲染，注意过滤掉不支持的标签。
只要这四步都通过，说明 Halo 自定义 API 接口已经成功对接小程序客户端。
后续你可以根据需要增加分页、分类筛选或搜索参数，但核心思路不变：Halo 提供数据，小程序负责展示。
