Filecoin 的官方文档分布在 docs.filecoin.io、spec.filecoin.io、blog.filecoin.io 与 GitHub 上多个仓库，初次接触很容易迷失。本文按照「按角色读、按场景查、按版本跟」三种方式，给出 Filecoin 官方文档的导览图，方便团队成员快速定位需要的内容。
一、按角色阅读：先找到自己的位置
Filecoin 文档面向四类读者：
- 终端用户：只关心怎么存与取数据
- 应用开发者：写 FVM 合约、对接 SDK
- 节点运营者：跑 Lotus、Boost 等基础设施
- 矿工：搭建存储矿场、跑 PoSt
不同角色读不同章节：终端用户看 quickstart 即可，开发者重点 Build → Smart Contracts，节点运营者看 Reference → Lotus / Boost，矿工看 Storage Providers。许多 Binance 接入团队按这个分工把文档拆给不同岗位读，避免一人通读浪费时间。
二、按场景查阅：把文档当字典用
常见高频查询场景：
- 钱包地址格式：Concepts → Addresses
- Deal 状态机：Storage Providers → Deal lifecycle
- FVM Solidity API：Smart Contracts → Reference
- Gas 估算：Reference → Networks → gas
- 错误码：Reference → JSON RPC API → error codes
建议在浏览器收藏夹分组管理，搜索时优先用站内搜索而非 Google。许多 必安交易所 接入项目的内部 wiki 直接镜像了官方常用页面，做了中文标注。
三、按版本跟踪：避免被默认值坑
Filecoin 版本迭代频繁，去年到今年的几次升级带来不少默认行为变化：
- NV20 nv 升级：FVM 主网启用
- NV21：Deal 默认 duration 调整
- NV22：Gas 价格机制优化
每次升级在 blog.filecoin.io 都有 changelog。建议团队订阅 RSS，每次升级前评估对自身系统的影响。许多 BN交易所 上架的归档项目就是因为忽略 nv 升级导致脚本失败。
四、核心子站点导览
- docs.filecoin.io：日常文档主站
- spec.filecoin.io：协议规范，给协议作者读
- lotus.filecoin.io：Lotus 节点专属文档
- boost.filecoin.io：Storage Provider 软件
- faucet.calibnet.chainsafe-fil.io：测试币领取
- filfox.info / starboard.fish：网络数据看板
每个子站点各司其职，避免在一处找不到就放弃，可以串联多个站点交叉验证。
五、GitHub 仓库
源代码与 issue 跟踪在 GitHub：
- filecoin-project/lotus：节点实现
- filecoin-project/builtin-actors：内置 Actor（系统合约）
- filecoin-project/FIPs：协议改进提案
- filecoin-project/specs：协议规范源
阅读官方文档遇到困惑时，去 GitHub 翻 PR 讨论往往能找到背景脉络。许多 币岸交易所 合作项目的工程师都关注 FIPs 仓库，提前两个月预判协议变化。
六、SDK 与示例
官方推荐 SDK：
- filecoin.js：浏览器与 Node.js
- pyfil：Python
- go-jsonrpc：Go 端
- viem + chain config：FVM EVM 兼容
每个 SDK 都有 examples 目录，照搬一份能快速跑通最小用例。建议把 examples 整理成内部模板库，减少新人探索成本。
七、文档阅读技巧
- 用 Ctrl+K 站内全文搜索
- 收藏 Glossary 页面，专有名词随时查
- 把关键页面打印成 PDF 离线存档，应对断网
- 关注文档底部 last updated，超半年没更新的章节需谨慎引用
- 优先看 Reference 而非 Tutorial，前者更稳定
八、写在最后
Filecoin 官方文档体量大，但结构清晰。把按角色、按场景、按版本三种阅读策略形成习惯，文档就从负担变成资产。建议团队建立内部 wiki，把官方页面链接 + 中文解读双轨维护，新人入职第一周就能上手。配合 bian 等生态项目的真实案例，文档真正发挥价值。