Redocly 生成 OpenAPI 接口文档踩坑实录｜Node 版本兼容 + 接口地址错误问题解决

背景：项目使用 OpenAPI3 规范，想用 @redocly/cli 一键打包成独立静态 HTML 接口文档，过程遇到两个典型问题：Node/npm 版本不兼容警告、生成出来文档接口请求地址变成 file://localhost:7087/xxx，记录完整排坑流程。

一、环境 & 初始安装报错

我的本地环境：

• Node：v18.20.4
• npm：9.5.1

执行全局安装命令：

powershell

npm i -g @redocly/cli

控制台警告日志：

plaintext

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@redocly/cli@2.69.0',
npm WARN EBADENGINE   required: { npm: '>=10', node: '>=22.12.0 || >=20.19.0 <21.0.0' },
npm WARN EBADENGINE   current: { node: 'v18.20.4', npm: '9.5.1' }
npm WARN EBADENGINE }

changed 1 package in 395ms

✅ 问题说明：新版 @redocly/cli 2.69.0 强制要求 Node >=22.12 或者 20.19~20.x，我本地 Node18 不满足要求。虽然安装成功，但是直接调用 redocly 命令大概率会异常 / 参数识别异常。

✅ 临时方案（不用升级 Node，推荐）：使用 npx 调用，npx 会自动拉取对应版本包执行，避开全局环境版本限制

powershell

npx @redocly/cli build-docs D:\Workstation\EASY-BEAUTY\docs\openapi.json -o D:\Workstation\EASY-BEAUTY\docs\开放平台接口文档.html --title "开放平台接口文档" --inlineBundle

补充：--inlineBundle 参数作用：把所有 js、css 内联进 HTML，输出单文件静态文档，发给其他人直接打开就能看，不需要部署服务。
备选长期方案：

1. nvm-windows 管理多 Node 版本，切换到 Node20.19+ / Node22.12+
2. 安装低版本 redocly（适配 Node18）：npm i -g @redocly/cli@1.25.0

二、重大坑：生成文档接口地址变成 file://localhost:7087/open-api/call/promotestrategy/getDxzhcxDetails

现象

HTML 文档打开后，接口预览地址不是我们后端真实域名，前缀变成了 file://localhost:7087，直接发起请求会报错，无法在线调试。

根因

OpenAPI 规范中，接口服务地址由顶层 servers 字段定义 ；如果 openapi.json 里面没有写 servers，Redoc 会自动把当前打开 HTML 的路径当成服务地址（本地文件打开就变成 file 协议、前端调试服务地址）。

修复方案（3 种，按推荐排序）

方案 1：直接修改 openapi.json（最简单，一劳永逸）

在 json 最顶层，和 openapi、info 同级，增加 servers 配置：

json

{
  "openapi": "3.0.3",
  "info": {
    "title": "开放平台接口文档",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "shturl.cc/kdM7rAL2H",
      "description": "正式环境"
    },
    {
      "url": "shturl.cc/ZHSXLWhQ5jRlOX",
      "description": "测试环境"
    }
  ],
  "paths": {
    // 原有所有接口path...
  }
}

url 写后端网关 / 服务根地址，后面 path 只需要写 /open-api/call/promotestrategy/getDxzhcxDetails，Redoc 会自动拼接。

修改完 json 后，重新执行上面的 npx build-docs 打包命令，生成 HTML，地址就正常了。

方案 2：SpringBoot 项目（SpringDoc / Knife4j 自动生成 openapi.json）后端直接配置

如果你是后端代码自动生成 OpenAPI，不用手动改 json，在 yml 配置：

yaml

springdoc:
  api-docs:
    enabled: true
  servers:
    - url: shturl.cc/ZHSXLWhQ5jRlOX
      description: 测试环境
    - url: shturl.cc/kdM7rAL2H
      description: 正式环境

重启项目，重新拉取 openapi.json，自带 servers 字段。

方案 3：redocly overlay 覆盖（不想修改原始 openapi.json）

新建 overlay.yaml

yaml

overlay: 1.0.0
info:
  title: 追加servers覆盖
actions:
  - target: "$"
    update:
      servers:
        - url: "shturl.cc/ZHSXLWhQ5jRlOX"

打包命令带上 overlay：

powershell

npx @redocly/cli build-docs openapi.json -o doc.html --overlay overlay.yaml

三、完整可用打包命令汇总

单文件打包（推荐，直接发给同事）

powershell

npx @redocly/cli build-docs D:\Workstation\EASY-BEAUTY\docs\openapi.json `
-o D:\Workstation\EASY-BEAUTY\docs\开放平台接口文档.html `
--title "开放平台接口文档" `
--inlineBundle

四、总结踩坑清单

1. @redocly/cli 新版本对 Node 版本要求很高，Node18 会警告，优先 npx 临时运行，或者切换 Node20/22
2. 接口地址异常 90% 都是缺失顶层 servers 配置，Redoc 没有后端地址参考，自动拿当前页面地址填充
3. --inlineBundle 非常实用，打包成单个 HTML，离线可用，适合交付、内部文档流转
4. 对比 knife4j、swagger-ui：Redoc 生成的静态文档排版清爽，适合对外开放平台文档

拓展：Redocly 还支持校验 OpenAPI 规范、拆分文档、批量导出，适合做接口文档自动化流水线。