企业官网建设流程全解析

• 后端

本篇技术指南围绕 instagram-private-api（NodeJS Instagram private API SDK）中HighlightsRepositoryHighlightsTrayResponseUser_dict接口展开，它描述了「高亮故事聚合（Highlights Tray）」接口返回的完整用户档案对象结构。读完本文，你将掌握该接口 21 个字段的逐一含义与类型、其在highlightsTray()调用链中的位置、嵌套对象biography_with_entities与friendship_status的详细结构，以及如何在 TypeScript 项目中读取与使用这些数据。

接口定位：来自哪一次 API 调用？

HighlightsRepositoryHighlightsTrayResponseUser_dict不是独立存在的响应体，而是HighlightsRepository.highlightsTray(userId)方法返回的根响应对象（HighlightsRepositoryHighlightsTrayResponseRootObject）内部嵌套的一个子对象。该方法定义于 src/repositories/highlights.repository.ts，向 Instagram 私信/私域 API 发送一次 GET 请求：

public async highlightsTray(userId: string | number): Promise<HighlightsRepositoryHighlightsTrayResponseRootObject> { const { body } = await this.client.request.send<HighlightsRepositoryHighlightsTrayResponseRootObject>({ url: `/api/v1/highlights/${userId}/highlights_tray/`, method: 'GET', qs: { supported_capabilities_new: JSON.stringify(this.client.state.supportedCapabilities), phone_id: this.client.state.phoneId, battery_level: this.client.state.batteryLevel, is_charging: Number(this.client.state.isCharging), will_sound_on: 0, }, }); return body; }

调用链如下：ig.highlights.highlightsTray(userId)→ 向https://i.instagram.com/api/v1/highlights/{userId}/highlights_tray/发起 GET 请求 → 返回根对象RootObject→ 其中tv_channel.user_dict即本文主题。也就是说，user_dict承载的是与用户 IGTV 频道关联的完整用户档案信息，与tray数组中每个高亮条目所携带的简化版user对象（HighlightsRepositoryHighlightsTrayResponseUser）形成互补。

根响应对象的嵌套关系

从 src/responses/highlights.repository.highlights-tray.response.ts 可以看到完整的嵌套结构：

HighlightsRepositoryHighlightsTrayResponseRootObject ├── tray: HighlightsRepositoryHighlightsTrayResponseTrayItem[] // 高亮聚合条列表 ├── show_empty_state: boolean ├── tv_channel: HighlightsRepositoryHighlightsTrayResponseTv_channel │ ├── id: string │ ├── items: HighlightsRepositoryHighlightsTrayResponseItemsItem[] │ ├── more_available: boolean │ ├── seen_state │ ├── title: string │ ├── type: string │ ├── max_id: null │ └── user_dict: HighlightsRepositoryHighlightsTrayResponseUser_dict // ← 本文主角 └── status: string

因此在实际使用中，访问路径为response.tv_channel.user_dict。

字段全览：21 个属性的类型与含义

HighlightsRepositoryHighlightsTrayResponseUser_dict定义于 src/responses/highlights.repository.highlights-tray.response.ts，共 21 个属性，按其语义可分为四组。

身份与基础信息

其中pk是整组数据中复用价值最高的字段：拿到它即可继续调用ig.highlights.highlightsTray(pk)递归获取该用户的高亮聚合，或结合ig.feed.user(pk)拉取时间线内容。注意pk为number类型，而 Instagram 的数字 ID 在部分场景下可能超过Number.MAX_SAFE_INTEGER，本仓库的请求层在 src/core/request.ts 中通过json-bigint（storeAsString: true）对超长数字做字符串化处理，理论上根响应中的超大数字会被转换为字符串，因此实际运行时pk可能呈现为字符串形态，类型声明与真实数据之间需要留意。

头像与档案链接

内容与互动统计

需要说明的是：latest_reel_media的类型声明为number，但对比TrayItem.latest_reel_media以及同文件中User接口将latest_reel_media声明为null（见 源码）的情况，可以推断该字段在不同上下文中可能返回时间戳或null，使用时建议先做空值防御。

简介与关系状态

嵌套对象一：biography_with_entities

biography_with_entities定义于 src/responses/highlights.repository.highlights-tray.response.ts：

export interface HighlightsRepositoryHighlightsTrayResponseBiography_with_entities { raw_text: string; // 简介纯文本，与 biography 内容一致 entities: any[]; // 实体数组，通常为空，或包含简介中被识别为链接/提及的实体片段 }

该结构源自 Instagram 服务端对简介文本的预解析：raw_text保留原文，entities理论上存放可点击的富文本片段（如 URL、@提及）。但仓库中其类型被声明为any[]，说明服务端返回结构多变、尚未被严格建模，消费时建议对entities做Array.isArray校验并逐个防御性取值。

嵌套对象二：friendship_status

friendship_status定义于 src/responses/highlights.repository.highlights-tray.response.ts：

export interface HighlightsRepositoryHighlightsTrayResponseFriendship_status { following: boolean; // 当前登录账号是否已关注该用户 outgoing_request: boolean; // 是否存在待处理的外发关注请求 is_bestie: boolean; // 是否在密友（Besties）列表中 is_restricted: boolean; // 是否已被限制（Restricted） followed_by?: boolean; // 该用户是否关注了当前登录账号（可选） blocking?: boolean; // 当前登录账号是否拉黑了该用户（可选） muting?: boolean; // 是否已静音（可选） is_private?: boolean; // 是否为私密账号（可选） incoming_request?: boolean;// 是否存在待处理的入站关注请求（可选） }

其中following、outgoing_request、is_bestie、is_restricted为必填，其余五个字段为可选（Optional），服务端在不同场景下可能省略。这一对象与FriendshipRepository.show()返回的关系信息同构，可在无需额外请求的情况下直接获得当前登录账号与目标用户的关注关系，用于实现「一键关注/取关」「显示密友标识」等业务逻辑。

实战示例：读取高亮聚合中的用户档案

以下示例演示完整的调用与数据读取流程，需要先初始化客户端并登录（参考 README.md 与 session 示例）：

import { IgApiClient } from 'instagram-private-api'; const ig = new IgApiClient(); ig.state.generateDevice(process.env.IG_USERNAME); // 登录后调用 await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD); // 目标用户的数字 ID const userId = 123456789; // 获取高亮聚合响应 const response = await ig.highlights.highlightsTray(userId); // 1) tv_channel.user_dict：完整用户档案 const userDict = response.tv_channel.user_dict; console.log({ pk: userDict.pk, username: userDict.username, fullName: userDict.full_name, isPrivate: userDict.is_private, isVerified: userDict.is_verified, mediaCount: userDict.media_count, followerCount: userDict.follower_count, followingCount: userDict.following_count, bio: userDict.biography, profilePicUrl: userDict.profile_pic_url, igtvVideos: userDict.total_igtv_videos, }); // 2) 读取关系状态（注意可选字段防御） const fs = userDict.friendship_status; if (fs) { console.log('我是否已关注对方:', fs.following); console.log('对方是否关注我:', fs.followed_by ?? '未知'); console.log('是否在密友列表:', fs.is_bestie); } // 3) 处理简介实体（any[] 需要防御） if (Array.isArray(userDict.biography_with_entities.entities)) { userDict.biography_with_entities.entities.forEach((entity) => { console.log('简介实体:', entity); }); } // 4) 结合 tray 继续遍历每个高亮条目 for (const item of response.tray) { console.log(`高亮标题: ${item.title}，封面: ${item.cover_media.cropped_image_version.url}`); }

运行前提：项目需安装instagram-private-api并配置好登录凭证；该接口属于私域 API，登录状态失效时会抛出IgLoginRequiredError等错误（见 src/errors）。

使用注意与边界

• 响应根对象的status字段：请求层在 src/core/request.ts 依赖body.status === 'ok'判定请求成功，因此正常响应中根对象的status恒为'ok'；异常时则抛出对应IgResponseError。
• 与简化版User的区别：tray[].user（HighlightsRepositoryHighlightsTrayResponseUser）仅包含 11 个基础字段且多数可选；而tv_channel.user_dict是完整档案快照，包含粉丝数、简介、关系状态等统计型数据，适用于需要展示「用户主页信息」的场景。
• any[]与可选字段：biography_with_entities.entities为any[]，friendship_status中部分字段为可选，真实响应可能缺省，编写消费代码时必须做空值与类型防御。
• 大整数风险：pk、media_count等数值字段声明为number，但仓库的请求层已将超长数字转为字符串，类型与运行时数据可能存在偏差，处理 ID 时建议统一按string | number对待。

关联文档与源码索引

• 接口文档：HighlightsRepositoryHighlightsTrayResponseUser_dict.md
• 嵌套对象：biography_with_entities（文档）、friendship_status（文档）
• 根对象与兄弟结构：RootObject、Tv_channel、TrayItem
• 源码定义：src/responses/highlights.repository.highlights-tray.response.ts
• 发起请求的仓库类：src/repositories/highlights.repository.ts，类文档见 docs/classes/repositories/HighlightsRepository.md
• 响应类型统一由 src/responses/index.ts 从./highlights.repository.highlights-tray.response导出，因此可以直接import { HighlightsRepositoryHighlightsTrayResponseUser_dict } from 'instagram-private-api'作为类型注解使用。

• 后端