小红书 SDK 方法

调用形式与单次请求配置Copy Anchor Link

Client 上的绑定 Fetcher 是 client.<平台>.fetcher.<方法>(options, requestConfig?)：cookie 已随 Client 绑好，第二个参数只作用于当前这一次调用，并与 Client 的实例级请求配置合并 —— 单次配置优先，headers 单独合并。

直接导出的裸 Fetcher 是 <平台>Fetcher.<方法>(options, cookie?, requestConfig?)：没有实例级配置，cookie 按次传，第三个参数直接作用于当前请求。amagi.<平台>Fetcher 与同名的命名导出（import { bilibiliFetcher } from '@ikenxuan/amagi'）是同一个对象。

两种形态都由端点注册表派生、走同一条执行管线、返回同一种信封，所以本页列出的方法名与参数对两者都成立。

用 Cookie 头覆盖单次调用的 cookieCopy Anchor Link

requestConfig.headers 里任意大小写的 Cookie（Cookie / cookie / COOKIE）都会替换本次调用实际使用的 cookie：绑定形态覆盖 Client 上绑定的那份，裸 Fetcher 形态覆盖第二个参数。这次调用用哪份 Cookie，只写这一处就够。

小红书的签名要从 Cookie 里读 a1，覆盖成空串会落到游客会话（只拿得到上游允许匿名读取的内容）；要换成另一份登录态，就覆盖成仍含 a1 的那一份：

const result = await client.xiaohongshu.fetcher.fetchNoteDetail(
  { note_id: 'n1', xsec_token: 'tk' },
  { headers: { Cookie: 'a1=xxx; web_session=xxx' } }
)

它只影响这一次请求，不改 Client 实例，也不影响同一实例后续的调用。

读取返回值：取 dataCopy Anchor Link

方法永不抛异常，返回的是信封：成功支有 data，失败支有 error，两支都有 message 与 meta，顶层没有 code。本页所有示例统一用 if (result.success) 收窄之后再读 result.data —— 四种读法里只有它既不必额外 import，收窄后的 data 又不带 | undefined：

四种读法的完整说明、失败分支的字段与三条逃生舱见响应类型。

大整数 ID 与响应类型Copy Anchor Link

默认 JSON 解析会把超出 JavaScript 安全整数范围的裸整数保留为十进制字符串，防止直播间、作品等 ID 被四舍五入。普通安全整数、浮点数和指数写法保持原样；显式文本响应和自定义 transformResponse 仍由调用方控制。响应 ID 的类型因此可能是 string | number，需要统一存储时可用 String(id)；不要先调用 Number() 再拼接请求。

新增端点只声明已有证据支持的响应字段；缺少完整成功响应样本的字段使用 unknown，使用前应检查对象、数组或字符串等实际结构。

已收录的端点在未提供 Cookie 时会初始化游客会话，并沿用当前请求的 User-Agent 和传输配置。同一客户端、UA 和请求配置下复用五分钟，并合并并发初始化；初始化失败后，下一次调用可以重试。不同客户端、代理、请求头或适配器等配置分别缓存；裸 Fetcher 也按其请求配置隔离。游客会话只能访问上游允许匿名读取的数据，需要登录的内容仍须传入有效登录 Cookie。

显式传入 web_session 或 userId 时，请保留与它配套的 a1。缺少 a1 会返回 error.kind: 'auth'、error.code: 'COOKIE_MISSING'，并且不发送请求。client.xiaohongshu.request 自定义请求不执行端点的游客初始化，调用方仍需提供有效的 a1。

本页之外：自定义请求Copy Anchor Link

本页是已收录的端点方法。要请求 amagi 尚未收录的接口，用 client.xiaohongshu.request（默认签名器按 method 选择：POST → xhs-post，其余 → xhs-get）。小红书那份 apiUrls 返回的是 { Url, Body, apiPath } 三段，三个键对应 url / config.data / amagi.signPath：

const d = client.xiaohongshu.apiUrls.noteDetail({ note_id: 'note-id', xsec_token: 'xsec_xxx' })
const r = await client.xiaohongshu.request.request({
  method: 'POST',
  url: d.Url,
  data: d.Body,
  amagi: { signPath: d.apiPath }
})

详见自定义请求。

Fetcher 方法Copy Anchor Link

fetchHomeFeedCopy Anchor Link

首页推荐笔记列表。端点 xiaohongshu.homeFeed，同一端点的 HTTP 形态。

取首页推荐流笔记。翻页要手动：把上一页响应的 cursor_score 传回来。

const result = await client.xiaohongshu.fetcher.fetchHomeFeed({
  num: 20
})

if (result.success) {
  console.log(result.data)
}

fetchNoteDetailCopy Anchor Link

笔记详细信息。端点 xiaohongshu.noteDetail，同一端点的 HTTP 形态。

取笔记正文与互动数据。要评论区用 noteComments。

const result = await client.xiaohongshu.fetcher.fetchNoteDetail({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}

xsec_token 可以从笔记的分享链接里取，形如 xsec_xxx。

fetchNoteCommentsCopy Anchor Link

笔记评论列表。端点 xiaohongshu.noteComments，同一端点的 HTTP 形态。

取笔记评论列表。number 指定目标条数，翻页由端点自动完成。游客身份下平台对本接口限流较紧：超限回 HTTP 461（伪装成成功的空壳），退避需分钟级、秒级无效；而且不传 number 会触发翻页、多烧一次请求 —— 传具体小值可把请求数降到 1。

支持声明式翻页：用 number 指定需要的条数，单页上限 50 条，游标的带入与停止条件由端点声明处理。

const result = await client.xiaohongshu.fetcher.fetchNoteComments({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}

v6 的 cursor 参数已由声明式翻页接管（小红书的 string 游标与抖音的 number 游标，语义差异收敛在端点声明里），调用方只说明要多少条。

fetchUserProfileCopy Anchor Link

用户主页信息。端点 xiaohongshu.userProfile，同一端点的 HTTP 形态。

取用户主页的资料与统计。笔记列表见 userNoteList。

const result = await client.xiaohongshu.fetcher.fetchUserProfile({
  user_id: '5xxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}

用户资料改用 JSON 接口，平台响应包含 data.basic_info、data.interactions 与 data.tab_public。SDK 的 result.data 是这份原始响应，所以资料位于 result.data.data。读取旧主页 HTML 初始状态路径的调用方需相应调整。

import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=...' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchUserProfile({ user_id: 'user-id' })
if (result.success) {
  const profile = result.data.data
  const nickname = profile?.basic_info?.nickname
  if (typeof nickname === 'string') console.log(nickname)
  console.log(profile?.interactions, profile?.tab_public)
}

这些字段目前是可选协议字段，未确认的内部结构保持 unknown；应像上例一样检查后再使用。

fetchUserNoteListCopy Anchor Link

用户笔记列表。端点 xiaohongshu.userNoteList，同一端点的 HTTP 形态。

取用户的笔记列表。翻页要手动：cursor 传上一页最后一条的 ID。

const result = await client.xiaohongshu.fetcher.fetchUserNoteList({
  user_id: '5xxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}

用户主页签发的 xsec_token 仍为必填，并与 xsec_source 一起传给上游。不要将笔记详情的 token 当作用户主页 token 使用。

fetchEmojiListCopy Anchor Link

表情列表。端点 xiaohongshu.emojiList，同一端点的 HTTP 形态。

取小红书表情列表，无参数。

无参数。

const result = await client.xiaohongshu.fetcher.fetchEmojiList({})

if (result.success) {
  console.log(result.data)
}

searchNotesCopy Anchor Link

笔记搜索结果列表。端点 xiaohongshu.searchNotes，同一端点的 HTTP 形态。

按关键词搜笔记。翻页手动传 page，并复用相同的 search_id / session_id；可指定排序和笔记类型。

const result = await client.xiaohongshu.fetcher.searchNotes({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}

可传 sort（general / popularity_descending / time_descending）与 note_type（0 全部、1 视频、2 图文）。接口使用手动页码 page；同一轮搜索翻页时，复用 search_id 与 session_id，每页的请求标识由 SDK 自动生成。

import amagi, { xiaohongshuUtils } from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=...' } })
const search = {
  keyword: '旅行',
  search_id: xiaohongshuUtils.sign.getSearchId(),
  session_id: xiaohongshuUtils.sign.getSearchSessionId()
}
const firstPage = await client.xiaohongshu.fetcher.searchNotes({ ...search, page: 1 })
const secondPage = await client.xiaohongshu.fetcher.searchNotes({ ...search, page: 2 })

searchUserCopy Anchor Link

搜索用户结果列表。端点 xiaohongshu.searchUser，同一端点的 HTTP 形态。

按关键词或小红书号搜用户，返回 user_id 等。翻页手动传 page。

const result = await client.xiaohongshu.fetcher.searchUser({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}

公开方法名是 searchUser，与 searchNotes 一致。支持关键词或小红书号查询，手动传 page / page_size 翻页。该接口的 code: 1000 只有同时出现 success: true 时才作为成功处理，其他接口沿用各自的业务码判定。

fetchSearchHotListCopy Anchor Link

搜索热榜。端点 xiaohongshu.searchHotList，同一端点的 HTTP 形态。

取小红书当前搜索热榜，无参数。

无参数。

const result = await client.xiaohongshu.fetcher.fetchSearchHotList({})

if (result.success) {
  console.log(result.data)
}

无业务参数，可调用 client.xiaohongshu.fetcher.fetchSearchHotList()。返回上游当前热榜；没有完整录制证据的条目字段保留为 unknown，使用前应自行收窄。

fetchSubCommentsCopy Anchor Link

子评论（楼中楼）列表。端点 xiaohongshu.subComments，同一端点的 HTTP 形态。

展开某条一级评论下的回复。number 指定目标条数，翻页自动完成。

支持声明式翻页：用 number 指定需要的条数，单页上限 10 条，游标的带入与停止条件由端点声明处理。

const result = await client.xiaohongshu.fetcher.fetchSubComments({
  note_id: '64xxxxxxxx',
  root_comment_id: '',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}

root_comment_id 是要展开的一级评论 ID，note_id 与 xsec_token 来自同一篇笔记。传入 number 指定目标回复数，SDK 每页最多请求 10 条并自动推进游标。无需传 v6 补丁里的 num 或 cursor。

fetchLiveRoomCopy Anchor Link

直播间信息。端点 xiaohongshu.liveRoom，同一端点的 HTTP 形态。

取指定直播间的当前信息。variant=h5 走 h5 接口，否则走 web；web 端请提供 request_user_id 或含 userId 的 Cookie。

const result = await client.xiaohongshu.fetcher.fetchLiveRoom({
  room_id: ''
})

if (result.success) {
  console.log(result.data)
}

room_id 使用字符串，避免 JavaScript 大整数精度丢失。默认 variant: 'web'，request_user_id 可显式传入，也可从 Cookie 的 userId 读取；variant: 'h5' 不使用这个参数。两种接口的返回字段可能不同，协议类型只声明已有证据支持的共同字段。

fetchLiveStatusCopy Anchor Link

直播状态。端点 xiaohongshu.liveStatus，同一端点的 HTTP 形态。

轮询指定直播间是否在播，返回体极小。

const result = await client.xiaohongshu.fetcher.fetchLiveStatus({
  room_id: ''
})

if (result.success) {
  console.log(result.data)
}

传入字符串 room_id 查询直播状态，默认 scene: 'share_out_of_app'。是否在播需读取上游返回的状态字段；HTTP 请求成功本身不代表直播正在进行。

fetchLiveSquareCopy Anchor Link

直播广场。端点 xiaohongshu.liveSquare，同一端点的 HTTP 形态。

取直播广场推荐列表，参数均可选。

const result = await client.xiaohongshu.fetcher.fetchLiveSquare({
  source: 0
})

if (result.success) {
  console.log(result.data)
}

无必填参数，默认获取 27 条推荐直播间。需要翻页时手动传入上游返回的 cursor_score；它不是 v7 的 number 自动分页端点。extra_info 在 SDK 中可传对象，通过 HTTP query 调用时可传 URL 编码后的 JSON 对象字符串。

注意事项Copy Anchor Link

• note_id 与 xsec_token 都可以从笔记的分享链接里提取
• 部分接口需要登录状态才能拿到完整数据
• 反爬较严格，建议控制请求频率

小红书的签名工具（xiaohongshuUtils.sign 的 extractA1FromCookie / getSearchId / generateXT 等）见工具集。