fuels-ts SDK API 参考站实现：基于 TypeDoc 的 docs-api 工作区详解

本篇围绕 apps/docs-api 这一应用展开：它是 fuels-ts（Fuel v2 的 TypeScript SDK）的 API 文档站，由 TypeDoc 从各子包的源码与 TSDoc 注释生成。读完本文，你会了解该文档站的主页结构（index.md）、TypeDoc 配置中每个字段的作用、pnpm + Turborepo 下的构建链路，以及 16 个包入口与 packages/ 目录实际结构之间的对应关系，从而能够在本仓库中定位、验证并复现整套 API 文档的生成流程。

1. docs-api：一个只含 4 个文件的应用

在 fuels-ts 这个 pnpm + Turborepo monorepo 中，apps/docs-api 是专门负责生成 SDK API 参考文档的工作区应用。它的全部文件只有 4 个：

文件	职责
index.md	文档站首页内容（TypeDoc 的 readme），包含站点标题与模块导航列表
typedoc.json	TypeDoc 核心配置：入口包列表、输出目录、站点名、导航链接等
package.json	声明私有包 docs-api 及构建脚本 build: "typedoc"
turbo.json	声明 build 任务的缓存输出为 src/**

从 package.json 可以看到关键信息：

{
  "private": true,
  "name": "docs-api",
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "build": "typedoc"
  },
  "devDependencies": {
    "fuels": "workspace:*",
    "typedoc": "0.26.3"
  }
}

两点值得注意：

• private: true 且版本号固定为 0.0.1，说明它是一个纯内部工具包，不会发布到 npm；
• devDependencies 里通过 workspace:* 依赖了聚合包 fuels，使 TypeDoc 能解析到 monorepo 内部包之间的类型引用；TypeDoc 固定使用 0.26.3 版本。

2. 站点首页 index.md：一句话定位 + 模块导航

index.md 会被 TypeDoc 作为首页渲染。其内容结构非常紧凑：

1. 一张 SDK Logo 图片（<picture> 元素，按浅色/深色主题切换两张图源）；

2. 一句话定位（第 6 行）：

   fuels-ts is a library for interacting with Fuel v2.

   即 fuels-ts 是用于与 Fuel v2 交互的 TypeScript 库，这是整个 SDK 的自我定位；

3. 一组徽章（测试状态、npm 上 fuels 包版本、文档入口、社区频道），分别指向 CI workflow、npm 包页面、官方文档站与社区；

4. 一个 Modules 导航列表（第 13–26 行），列出 12 个模块：

   abi-coder、abi-typegen、account、address、crypto、errors、hasher、math、program、script、transactions、utils。

需要注意链接的解析基准：index.md 中的模块链接形如 modules/_fuel_ts_abi_coder.html，这是 TypeDoc 生成站点（输出目录 src/api，见下文）内部的相对路径，解析基准是生成后的站点根，而不是仓库根目录——因此在本仓库中不应按相对路径直接访问这些链接，它们是构建产物的页面文件名。

首页模块列表与仓库实际包结构的差异

将 index.md 的 12 个模块与 packages/ 目录实际内容对照，可以观察到两处不一致（均为对现状的客观描述）：

• index.md 的列表未包含 contract、recipes、merkle 等实际存在的包。contract（合约工厂与合约调用）、recipes（Sway 程序模板示例，其 package.json 描述为 “Recipes for Sway Programs”）等都有独立源码目录，但未出现在首页导航中；
• 反过来，typedoc.json 的入口列表里包含 packages/interfaces 与 packages/predicate，而当前仓库 packages/ 目录下并不存在这两个目录。从源码结构看，这很可能是包拆分/迁移历史留下的陈旧配置（谓词、接口相关能力如今分布在 account、program 等包中），但配置本身尚未清理。

这类“首页导航、TypeDoc 入口、真实目录”三者不一致的情况，正是阅读 API 文档生成配置时需要特别注意的地方。

3. typedoc.json：逐项解读核心配置

apps/docs-api/typedoc.json 是理解整个文档站的关键，全文仅 31 行：

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPointStrategy": "packages",
  "entryPoints": [
    "../../packages/abi-coder",
    "../../packages/abi-typegen",
    "../../packages/address",
    "../../packages/interfaces",
    "../../packages/predicate",
    "../../packages/account",
    "../../packages/program",
    "../../packages/contract",
    "../../packages/script",
    "../../packages/utils",
    "../../packages/crypto",
    "../../packages/errors",
    "../../packages/hasher",
    "../../packages/math",
    "../../packages/transactions",
    "../../packages/recipes"
  ],
  "out": "src/api",
  "readme": "./index.md",
  "name": "Fuels TS SDK API Documentation",
  "navigationLinks": {
    "Docs": "…官方文档站…",
    "GitHub": "…项目源码仓库…"
  },
  "logLevel": "Error"
}

各字段的作用：

字段	取值	作用
entryPointStrategy	packages	以 npm 包为入口单元解析类型：TypeDoc 会读取每个入口的 package.json 来确定包名与类型入口，而不是以单个 TS 文件为单位
entryPoints	16 个包路径	文档化范围：从 apps/docs-api 出发，以 ../../packages/* 相对路径列出。当前 packages/ 下还有 create-fuels、fuel-gauge、fuels、logger、merkle、versions 等包不在入口列表中——其中 fuels 是纯再导出聚合包，create-fuels 是脚手架 CLI、fuel-gauge 是测试包，不单独生成 API 文档是合理的取舍
out	src/api	生成的静态站点输出到 apps/docs-api/src/api/ 下
readme	./index.md	首页取自该 Markdown 文件（即第 2 节分析的内容）
name	Fuels TS SDK API Documentation	站点标题
navigationLinks	两个外部链接	在文档站导航栏提供通往官方使用文档与源码仓库的跳转（外链地址见配置文件原文，本文不重复罗列）
logLevel	Error	配置注释写明“Suppress all the warnings that are being thrown by typedoc”，即把日志级别提到 Error，压制生成过程中的告警噪音

与 typedoc.base.json 及子包配置的关系

仓库根目录还有一份 typedoc.base.json，内容只有 includeVersion: true（表示生成的文档携带 SDK 版本号）。各子包（如 packages/abi-coder/typedoc.json）各自维护一份继承自它的配置，形如：

{
  "extends": ["../../typedoc.base.json"],
  "entryPoints": ["src/index.ts"],
  "readme": "none"
}

也就是说，每个包既可以独立生成带版本的 API 文档，也可以被 docs-api 聚合为一个统一站点。docs-api 使用 entryPointStrategy: "packages" 时，TypeDoc 正是借助各包的 package.json 与其入口配置来解析类型的。

4. 构建链路：pnpm workspace → Turborepo → typedoc

文档站的构建完全嵌入 monorepo 的标准流程：

1. 依赖安装：根 package.json 声明运行环境为 Node ^20.0.0 || ^22.0.0 || ^24.0.0、pnpm ^9.4.0（packageManager: pnpm@9.4.0），工作区结构由 pnpm-workspace.yaml 定义；
2. 构建编排：根 turbo.json 定义 build 任务依赖 ^build 与 prebuild、产物缓存为 dist/**；而 apps/docs-api/turbo.json 将其覆盖为 outputs: ["src/**"]，即文档站的缓存产物就是输出目录 src/api（src/**）下的静态文件；
3. 执行生成：apps/docs-api 的 build 脚本就是裸的 typedoc 命令，由 TypeDoc 读取当前目录的 typedoc.json 完成整个站点生成。

因此在本仓库中复现文档生成，只需安装依赖后在 monorepo 根执行 turbo 过滤构建（例如 pnpm turbo run build --filter=docs-api），或进入 apps/docs-api 目录执行 pnpm build，产物会落在 apps/docs-api/src/api/ 中。由于 TypeDoc 以包为入口解析类型，建议先完成各 packages/* 的构建（根脚本 pnpm build:packages 会构建除 docs 与模板外全部包），以让入口解析稳定。

5. 文档化对象：fuels 聚合包与各子包

index.md 声明 fuels-ts 是“与 Fuel v2 交互的库”，而 API 文档站实际上就是把 packages/ 下的能力分层暴露给开发者。从各包 package.json 的元信息看，当前各包统一处于 0.103.0 版本，命名遵循 @fuel-ts/* 前缀（聚合包为 fuels），职责划分清晰：

• abi-coder / abi-typegen：ABI 编解码，以及“Generates Typescript definitions from Sway ABI Json files”的 TypeScript 定义生成器（对应文档站入口中的 abi-typegen）；
• account：账户、钱包、Provider、连接器等（入口数最多的包之一，含 wallet、providers、connectors、hdwallet、predicate 等子模块目录）；
• address：“Utilities for encoding and decoding addresses”；
• crypto：“Utilities for encrypting and decrypting data”，提供浏览器/Node 双端实现；
• errors：“Error class and error codes that the fuels-ts library throws”；
• hasher：“Sha256 hash utility for Fuel”；
• math、merkle：数值计算与默克尔树（merkle 未纳入文档站入口）；
• program、contract、script、transactions、utils、recipes：程序调用、合约/脚本执行、交易构造、通用工具与示例配方。

所有面向使用者的 API 最终由聚合包统一出口。packages/fuels/src/index.ts 通过 export * from '@fuel-ts/…' 把 abi-coder、account、address、contract、crypto、errors、hasher、math、program、recipes、transactions、utils 等子包（含 configs 子路径）再导出，并额外导出 @fuels/vm-asm 的 FuelAsm 命名空间与 CLI 编程接口。这与 typedoc.json 入口列表高度吻合——API 文档站的模块划分基本就是 SDK 公开 API 的划分。

6. 阅读该配置时的注意点

结合仓库现状，使用或评审 docs-api 配置时建议核对以下几点：

1. 入口列表含失效路径：typedoc.json 中的 ../../packages/interfaces 与 ../../packages/predicate 在 packages/ 目录下不存在。TypeDoc 的 logLevel: "Error" 会压制告警，这类问题在生成日志中不易暴露，需人工核对入口与真实目录的一致性；
2. 首页导航不完整：index.md 的 Modules 列表只有 12 项，缺少 contract、recipes 等实际入口包，读者从首页出发不一定能浏览到全部模块页；
3. 链接基准不同：首页模块链接相对生成站点（src/api）解析，而非仓库根目录；
4. 输出目录即缓存产物：out: "src/api" 与 turbo.json 的 outputs: ["src/**"] 配合，使增量构建可基于输出目录做缓存；
5. 版本随包更新：typedoc.base.json 的 includeVersion 会把包版本（当前各包均为 0.103.0）写入文档，阅读生成产物时可据此判断对应 SDK 版本。

7. 小结

apps/docs-api 用一个极小的应用（一个 Markdown 首页 + 一份 TypeDoc 配置 + 一条 typedoc 构建脚本）支撑起 fuels-ts 的 API 参考站：以 entryPointStrategy: "packages" 将 packages/ 下 16 个入口包（含 contract、recipes 等）聚合为统一站点，首页由 index.md 提供定位语（“fuels-ts is a library for interacting with Fuel v2”）与模块导航，产物输出到 src/api 并纳入 Turborepo 缓存。理解这一流程后，开发者既能顺着 typedoc.json 的入口列表快速定位各模块源码目录（如 packages/abi-coder、packages/account），也能在维护文档站时准确判断入口配置、首页导航与实际包结构之间的偏差。