快速上手
三步上手：创建客户端、获取数据、按 success 读取返回值
快速上手
安装完成后，从创建客户端到获取第一条数据，大致分三步，下面逐步说明。
第一步：创建客户端
amagi() 接收各平台的 Cookie，返回一个客户端实例。此后的所有请求都通过它发起，无需重复传入 Cookie：
import from '@ikenxuan/amagi'
const = ({
: {
: 'SESSDATA=xxx; bili_jct=yyy; ...',
: 'ttwid=...; ...',
: 'did=...; ...',
: 'a1=...; ...'
},
: {
// 如需自定义请求头、超时、代理，在此配置（可选）
: { 'User-Agent': 'Mozilla/5.0 ...' }
}
})关于 Cookie 的获取：登录对应平台的网页版，在浏览器开发者工具中完整复制请求头里的 Cookie。用不到的平台留空字符串即可，无需四个平台全部填写。
第二步：获取数据
通过 client.<平台>.fetcher 调用对应的方法。下面四个平台各举一例，均为获取一条作品或视频的详情：
// 获取视频信息
const video = await client.bilibili.fetcher.fetchVideoInfo({
bvid: 'BV1xx411c7mD'
})
if (video.success) {
console.log(video.data)
}
// 获取评论
const comments = await client.bilibili.fetcher.fetchComments({
oid: '170001',
type: 1,
number: 20
})第三步（可选）：启动 HTTP 服务
如果不想在代码中直接调用，而是希望通过 HTTP 请求获取数据（例如供其他语言或进程使用），在客户端上调用 startServer，即可将其启动为本地服务：
import from '@ikenxuan/amagi'
({
: {
: 'SESSDATA=xxx; ...',
: 'ttwid=...; ...',
: 'did=...; ...',
: 'a1=...; ...'
}
}).(4567)
// 在浏览器中打开 http://localhost:4567/ 查看接口列表
// 在线调试：https://amagi.apifox.cn该服务默认不带鉴权，任何能访问此端口的人都可以使用你的 Cookie 发起请求。请仅在本机使用，或在其前自行添加一层访问控制，不要直接暴露到公网。
不创建客户端的调用方式
如果只是临时调用少数几个接口，不想先创建客户端，可以直接使用静态方法，代价是每次都要手动传入 Cookie：
import from '@ikenxuan/amagi'
const = await ..({ : 'BV1xx411c7mD' }, 'SESSDATA=...')如何读取返回值
每个方法都返回同一种结构。先判断 result.success：为 true 时，result.data 即为数据；为 false 时，result.error 是错误详情。在 TypeScript 中，只有先判断过 success 才能访问 data，因此这个 if 判断不可省略：
const = await ...({
: 'BV1xx411c7mD'
})
if (.) {
.data} else {
// 失败分支没有 data，只有 error（kind / code / message 等）
.(.., ..)
}类型是根据真实响应逐一编写的，偶尔会滞后于平台新增的字段。即使遇到类型中未声明的字段，同样可以读取（读取结果为 unknown，需自行判断后再使用），也可以用泛型将返回类型替换为自定义类型。这几种写法在响应类型中有详细说明。
记录请求日志
如果想知道每次请求发往何处、耗时多少、是否发生重试，可以通过客户端的事件总线订阅，调用 client.on 即可。每条事件都带有 meta，上述信息都在其中：
// 一次调用成功
.('api:success', () => {
.(`[${..}] ${..} 成功，耗时 ${..}ms`)
})
// 一次调用失败：error 中包含错误的类型与原因
.('api:error', () => {
.(`[${..}] ${..} 失败: ${..}`)
})
// 底层每发出一条 HTTP 请求都会触发一次
.('http:request', () => {
.(.., .., ..)
})包顶层还导出了一个 amagiEvents，那是为 v6 旧代码保留的另一条总线，接收不到 client.on 上的事件，请勿将两者混淆。完整的事件名与两条总线的分工见事件系统。
下一步
最后更新于 2026-09-28