DevDocs 如何用 thor docs:download 与 docs:list 下载和更新预生成的文档包？-平芜编程栈

DevDocs 如何用 thor docs:download 与 docs:list 下载和更新预生成的文档包？

【免费下载链接】devdocsAPI Documentation Browser项目地址: https://gitcode.com/GitHub_Trending/de/devdocs

在本地搭建 DevDocs（一个聚合多份 API 文档并提供即时搜索的浏览器）时，需要把预生成的文档包从 DevDocs 的服务器下载到本地，再由 Sinatra 应用读取。本文对应的任务是：克隆 DevDocs 仓库后，用thor docs:list查看可用的文档及版本，用thor docs:download按需下载或更新文档包，最后启动本地服务确认下载的文档能正常访问。

适用前提（来自 README.md 的 Manual Installation 一节）：

Ruby 4.0.6（版本在Gemfile中定义）
libcurl
一个 ExecJS 支持的 JavaScript 运行时（macOS 和 Windows 自带；Linux 上需要 Node.js）

准备：克隆仓库并安装依赖

以下命令按顺序在终端中执行：

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs gem install bundler bundle install

README 特别提醒：如果系统上安装了多个 Ruby 版本，后续所有thor命令都必须通过bundle exec执行（例如bundle exec thor docs:download --default）。

用 thor docs:list 查询文档名和版本

下载之前先确认目标文档的确切名称和版本：

thor docs:list

该命令列出当前项目支持的全部文档，带版本的文档会以名称@版本号的形式逐行输出，结果通过tty-pager分页显示。实现位于 lib/tasks/docs.thor。

docs:list还有一个--packaged选项，但它列出的是本地已经打包（*.tar.gz）的文档，用于维护者流程，普通下载场景不需要。

另外，运行thor list可以在项目根目录查看 CLI 提供的所有命令和选项。

下载文档包

thor docs:download的用法为（见 lib/tasks/docs.thor）：

thor docs:download (<doc> <doc@version>... | --default | --installed | --all)

按目标选择参数：

按需下载：直接传一个或多个文档名，如
```
thor docs:download html css
```
带版本的文档必须用名称@版本格式指定版本，例如thor docs:download node@10\ LTS（README.md 与 docs/maintainers.md 中均以rails@5.2这类写法举例）。不带版本时，docs:download会取该文档定义的第一个版本。
--default：下载 README 手动安装流程推荐的默认集合（css dom html http javascript，定义于 lib/docs.rb）。首次安装走这条路径即可。
--all：下载并安装本项目支持的全部文档。Docker 镜像构建时用的就是这个选项（见 Dockerfile 中的thor docs:download --all）。
--installed：重新下载所有已经下载过的文档，即"更新全部已装文档"的命令，详见下文。

下载过程的输出形如：每处理完一个文档打印一行(序号/总数) 文档名版本 OK，失败时打印FAILED (异常类: 异常信息)；全部完成后打印Done。命令结束后还会自动重新生成清单文件（generate_manifest），该清单写入public/docs/docs.json，供应用端知道系统上当前有哪些文档。

启动服务并验证

下载完成后启动服务器：

bundle exec rackup

然后把浏览器指向 localhost:9292。按 README.md 的说明，第一次请求会花几秒编译 assets，之后即可正常浏览——这就是"下载成功"的可核对结果：页面中能看到刚下载的文档集，并可用侧边栏的文档选择界面勾选要启用的文档。

如果某行输出是FAILED，检查网络与文档名拼写；文档名错误时会看到ERROR: ...以及提示Run "thor docs:list" to see the list of docs and versions.，回到上一步核对名称和版本即可。

更新已下载的文档

README 明确说明：项目目前没有别的更新机制，更新分两部分：

git pull origin main # 更新代码 thor docs:download --installed # 下载所有已装文档的最新版本

--installed的范围由本地public/docs下存在的index.json决定（见 lib/docs.rb 的Docs.installed），所以它只会更新你已经下载过的文档，不会拉取新的。

限制与常见问题

依赖生产环境：thor docs:download下载的是维护者通过thor docs:upload上传到生产的包（下载源为 downloads.devdocs.io，见 docs/maintainers.md）。如果某个新文档的 PR 已合并但文件尚未上传到生产，对该文档的docs:download会失败——这不是本地环境问题。
public/docs/docs.json不要提交：它只反映本地下载/生成过哪些文档，全新 clone 下应为空（docs/maintainers.md 明确要求 never commit）。
可选分支--rclone：docs:download支持--rclone选项，改用rclone copy devdocs:devdocs-downloads/<path>.tar.gz ...从远端拉包（lib/tasks/docs.thor），需要本机已配置好 rclone 的devdocs远端；默认路径用 HTTP 直接下载，一般无需此选项。
不要本地重新抓取：对大多数文档，直接docs:download拿官方测试过的版本即可；thor docs:generate会向源站发起数千次 HTTP 请求，README 与 docs/maintainers.md 都建议只在修改 scraper 代码时才运行。