Ferritin — Rust documentation

🩸 Ferritin

基于终端的 Rust 文档查看器

Ferritin 读取 rustdoc JSON 输出，直接在终端中显示 Rust 文档。它支持本地工作区 crate、标准库文档和来自 crates.io 的 crate，并提供搜索功能以及现代终端特性，包括鼠标支持、语法高亮和可点击链接。

功能

• 交互式文档浏览器，支持键盘和鼠标导航
• 单次运行的 CLI，可在终端中快速查找文档
• 跨 crate 搜索或在指定 crate 中搜索
• 可在三种场景中无缝使用：
  • 本地工作区 crate（需要 nightly 工具链）
  • 标准库（需要 rust-docs-json rustup 组件）
  • 来自 crates.io 的 crate（按需从 docs.rs 获取）
• 现代终端 UI，支持斜体、Unicode 方框绘制、语法高亮、OSC8 超链接、支持的终端中的光标变化，以及鼠标悬停预览等特性
• 快速导航，带有历史记录和面包屑路径

安装

预编译二进制文件（推荐）

预编译二进制文件无需编译，适用于 x86_64/aarch64 macOS、x86_64 Linux 和 x86_64 Windows。

如果你已安装 cargo-binstall，它会读取 发布元数据并为你的平台安装合适的二进制文件：

cargo binstall ferritin

否则，安装脚本会检测你的平台，下载匹配的二进制文件，并将其 放到 ~/.cargo/bin 中：

macOS 和 Linux：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jbr/ferritin/releases/download/ferritin-latest/ferritin-installer.sh | sh

Windows（PowerShell）：

powershell -c "irm https://github.com/jbr/ferritin/releases/download/ferritin-latest/ferritin-installer.ps1 | iex"

以上两种方式始终会安装最新版本。你也可以选择特定 版本，或直接从[发布页面]下载压缩包。

从源代码安装

若要从源代码构建（或用于没有预编译二进制文件的平台）：

cargo install ferritin

可选：标准库文档

若要查看 std、core 和 alloc 的文档：

rustup component add rust-docs-json

查看本地工作区文档

本地 crate 文档需要 nightly 工具链：

rustup toolchain install nightly

注意：ferritin 的版本与 nightly 工具链版本相关。Ferritin 支持一系列较新的 rustdoc JSON 格式版本；如果你的 nightly 生成了更新的 格式，ferritin 会尽力解析。

用法

交互模式

启动交互式浏览器：

ferritin -i

启动后，使用 h 或 ? 查看可用的按键绑定。基本导航：

• g - 按路径跳转到某个条目（例如，std::vec::Vec）
• s - 搜索（按 Tab 在当前 crate 和所有 crate 之间切换）
• l - 列出可用的 crate
• 使用方向键、j/k 或鼠标导航
• 点击链接即可跳转

CLI 模式

查看特定条目的文档：

ferritin get std::vec::Vec
ferritin get serde::Serialize

搜索条目：

ferritin search "hash map"
ferritin search --crate tokio "spawn"

列出工作区中可用的 crate：

ferritin list

输出格式

Ferritin 会自动检测渲染方式：在终端中使用 ANSI 颜色，通过管道传输时使用纯文本，在编码 Agent 下使用精简的 Markdown 风格格式。使用 --format <tty|plain|agent|json> 覆盖默认格式。--format json 会输出结构化表示——对于 get，输出已解析条目；对于 search/list，输出搜索或列表结果——供脚本和程序化使用者使用：

ferritin get std::vec::Vec --format json

（随着库 API 的演进，JSON 结构仍在调整；计划发布 JSON Schema。）

缓存与存储

Ferritin 将缓存保存在单个目录下：如果设置了 $FERRITIN_HOME，则使用该目录；否则使用 $XDG_CACHE_HOME/ferritin；再否则使用 ~/.cache/ferritin。其中的所有内容都可以重建（通过获取或派生生成），因此始终可以安全删除：

• Crates.io 文档：原始 rustdoc JSON 存放在 docs/{crate}/{version}/{format-version}.json，旁边还有派生的二进制缓存 （用于快速部分加载的 rkyv 归档，以及首次搜索时延迟生成的 .index 文件）
• crates.io 元数据：用于版本解析和输入联想的 crate 名称文件（crate-names/），以及各 crate 的版本查询文件 （crates-io-versions/）
• 标准库搜索索引：如果可用，则写入 {rustc sysroot}/share/doc/rust/json/
• 本地工作区文档：构建在工作区自身的 target/doc/ 中，而非共享缓存

早期版本将缓存存放在 $CARGO_HOME/rustdoc-json 下；首次运行时会自动迁移在那里找到的缓存。

环境变量

变量	含义
FERRITIN_HOME	覆盖缓存根目录（见上文）
FERRITIN_THEME	默认配色主题（等同于 --theme）
FERRITIN_CRATE_NAMES_URL、FERRITIN_CRATE_DESCRIPTIONS_URL	覆盖获取 crate 名称文件的位置（例如镜像站）

ferritin serve（可选的 serve/acme 功能；分发的二进制文件不包含这些功能）采用 12-factor 风格进行配置：

变量	含义
HOST、PORT	绑定地址（:: 会绑定双栈）
FERRITIN_CACHE_BYTES	内存中 crate 缓存的权重上限
FERRITIN_RSS_HIGH_WATER_BYTES	RSS 防护阈值（仅限 Linux）：匿名 RSS 超过此值时减少缓存权重
FERRITIN_RATELIMIT	每个客户端每分钟可发送的 /api 请求数
FERRITIN_ACME_DOMAIN	为此域名启用通过 Let's Encrypt 自动配置 HTTPS
FERRITIN_ACME_CACHE_DIR	使用 ACME 时必需：用于持久保存账户密钥和证书
FERRITIN_ACME_CONTACT	可选的 ACME 联系邮箱
FERRITIN_ACME_PRODUCTION	使用 Let's Encrypt 生产环境目录（默认：测试环境）

仅供开发使用的参数（不属于稳定接口）：FERRITIN_TEST_MODE（规范化快照测试输出）、FERRITIN_REINDEX（在内存中重建搜索索引，绕过磁盘缓存），以及搜索评分探针 FERRITIN_NAME_WEIGHT、FERRITIN_ANCESTOR_WEIGHTS 和 FERRITIN_NAME_PREFIX_COUNT。

当前状态

Ferritin 当前处于 0.x 版本，作者正将其作为主要文档界面积极使用。它已可供一般用途使用，但输出格式尚不稳定，版本之间可能会发生变化。

如果你使用脚本处理 ferritin 的输出，请注意文本格式可能会变化。请固定使用特定版本，或做好更新脚本的准备。

平台支持

Ferritin 主要在类 Unix 系统上开发，也会在 Windows 上测试；CLI 和交互式 TUI 均可在 Windows 上运行（提供预构建的 x86_64 Windows 二进制文件）。如果你在任何平台上遇到问题，请提交 issue 或 pull request。

相关项目

Ferritin 最初是为支持 rustdoc-mcp MCP 服务而开发的，该服务为 Claude Code 和其他 MCP 客户端提供 Rust 文档访问功能。

许可证

^{你可以选择采用 Apache License，版本 2.0 或 MIT 许可证进行许可。}

---

_{除非你明确另行说明，否则根据 Apache-2.0 许可证的定义，你为纳入此 crate 而有意提交的任何贡献，都将按照上述条款进行双重许可，不附加任何条款或条件。}