Chirpy SDK 开发者指南：如何用几行代码管理评论项目

Chirpy SDK 开发者指南：如何用几行代码管理评论项目

【免费下载链接】chirpy💬 A privacy-friendly and customizable Disqus (comment system) alternate. 注重隐私保护和定制化的评论系统。项目地址: https://gitcode.com/gh_mirrors/ch/chirpy

Chirpy SDK（@chirpy-dev/sdk）是 Chirpy 提供的官方 JavaScript SDK，让你用几行代码就能完成评论项目的创建、查询和删除，还能管理页面与用户。对于想把自己的站点接入 Chirpy 评论系统、或希望批量自动化管理多个项目的开发者来说，它是最高效的工具。

一键安装 Chirpy SDK

在项目中安装 SDK，支持常见的包管理器：

npm i -S @chirpy-dev/sdk

SDK 源码位于 packages/sdk/src/sdk.ts，核心就是一个ChirpySDK类，内部通过fetch调用 Chirpy 的 SDK 专用接口。

获取 SDK API Key（最快配置方法）

所有 SDK 请求都需要一个 API Key：

1. 在 Chirpy 控制台的 Account 页面生成以cpk_开头的 SDK Key
2. 用这个 Key 初始化 SDK 实例

import { ChirpySDK } from '@chirpy-dev/sdk'; // SDK Key 以 cpk_ 开头，请勿泄露 const sdk = new ChirpySDK('cpk_xxxxx');

请求时 SDK 会自动把 Key 放入Authorization: Bearer请求头，服务端接口 apps/main/src/pages/api/sdk/project.ts 会校验它是否有效。

用几行代码管理评论项目

SDK 提供三个项目级方法，覆盖评论项目的完整生命周期：

// 查询、创建、删除，各只需一行 const project = await sdk.getProject('acme.com'); const peak = await sdk.createProject('peak.com', 'Peak'); await sdk.deleteProject('peak.com');

💡 两个实用细节：

• 创建是幂等的：服务端使用 upsert 逻辑，同一个域名重复调用createProject只会更新项目名称，不会报错
• 项目数量有上限：PRO 套餐最多 10 个项目，超出会返回 403，此时需升级套餐

进阶：页面与用户管理

除了项目，SDK 还支持两类常用操作（见 packages/sdk/src/sdk.ts）：

• getPage(url)：根据文章 URL 查询页面信息及其评论列表
• linkPageAuthor(params)：把文章作者绑定到指定页面
• createUser(email, name)：在 Chirpy 中创建一个用户

const page = await sdk.getPage('https://acme.com/blog/hello'); await sdk.createUser('author@example.com', 'Acme Author'); await sdk.linkPageAuthor({ pageUrl: 'https://acme.com/blog/hello', email: 'author@example.com', name: 'Acme Author', });

典型场景：在 CMS 发布新文章后自动调用linkPageAuthor，让作者发布文章时无需手动登录 Chirpy 认领。

错误处理与调试技巧

SDK 对非 2xx 响应会直接抛出带状态码和响应体的Error，因此建议在调用处加try/catch：

try { const project = await sdk.getProject('acme.com'); } catch (error) { console.error(error.message); // 包含 status 和详细信息 }

常见错误速查：

• 401：API Key 缺失或无效
• 400：参数缺失（如没有传domain）
• 403：项目数量超限（PRO 套餐上限 10 个）

🔍 调试时建议先设置环境变量保存 Key（如CHIRPY_SDK_KEY），避免把密钥硬编码进代码；官方测试脚本 packages/sdk/src/sdk.test.ts 展示了本地联调的完整流程。

总结

Chirpy SDK 把评论项目的管理压缩到了三行代码：

1. 安装@chirpy-dev/sdk并获取cpk_开头的 API Key
2. 用createProject/getProject/deleteProject管理评论项目
3. 借助getPage、createUser、linkPageAuthor打通 CMS 工作流

如果你正在寻找一个注重隐私保护、又支持代码化配置的 Disqus 替代品，这套 SDK 会让 Chirpy 的接入体验非常顺滑。🚀

【免费下载链接】chirpy💬 A privacy-friendly and customizable Disqus (comment system) alternate. 注重隐私保护和定制化的评论系统。项目地址: https://gitcode.com/gh_mirrors/ch/chirpy