Redocly CLI 与 Redoc：从 lint 到静态文档交付

Redocly 契约交付流水线规则配置、lint、bundle 与文档制品必须锁版、可审查、可回滚。高清原图

先固定 CLI 与配置

Redocly CLI 是处理 OpenAPI 的独立命令行工具；Redoc 是开源文档渲染器，Redocly 平台则是另一套托管边界。不要把三者统称为“Redoc 页面”。项目把版本锁进开发依赖，并在根目录维护 redocly.yaml：

npm install --save-dev --save-exact @redocly/cli
npx redocly --version
npx redocly lint docs/api/openapi.yaml
npx redocly bundle docs/api/openapi.yaml -o build/openapi.bundle.yaml

CLI v2 对 Node.js 有明确运行时要求；runner 镜像和 lockfile 要一起审查。使用 @latest 适合临时查看，不适合作为可重复流水线。

lint 规则是一项团队政策

默认规则只能提供起点。operationId、错误模型、鉴权、命名与 examples 等规则要对应团队消费者和发布边界。新规则先对存量观测，再设 owner 与整改期限；未解析引用、结构错误和安全定义缺失不应长期降为 warning。

bundle 的输出是交付制品，不是编辑源。CI 应在干净 checkout 中执行 lint 和 bundle，并确认产物不含远程引用失败、内网地址与真实数据。大型契约记录文件数、引用数、lint 时长和 bundle 大小，增长后按 API owner 分拆入口，而不是用问题上限隐藏债务。

文档发布需要单独审查

Redoc 可以生成自托管参考文档；托管平台、预览链接和上传命令会改变数据去向。内部契约默认本地构建到受控静态站点，公共发布使用过滤后的 artifact。Markdown HTML、远程资源、自定义插件和主题代码都按不可信输入处理。

升级采用旧版/新版双跑，比较诊断、bundle 和静态输出；异常时恢复 lockfile、Node 镜像和规则配置。停用 Redocly 工具链时，保留标准 OpenAPI 主源与消费者清单，删除平台 token、预览项目和构建缓存，再选择其他兼容工具验证退出。

官方资料：Redocly CLI、CLI commands、Redoc 文档交付。