如何解决ReDoc无法展示本地OpenAPI定义文件的问题？

云上老周

2026-8-2

使用ReDoc展示本地OpenAPI定义文件的解决方案

问题背景

ReDoc可正常加载远程openapi.json文件（示例代码如下），但将文件保存到本地后，通过file://协议指定本地路径时，会触发process is not defined的错误。

远程加载的正常代码：

<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>ReDoc - openapi.json</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <style>
body {
  margin: 0;
  padding: 0;
}
</style>
  </head>
  <body>
    <redoc spec-url="https://petstore3.swagger.io/api/v3/openapi.json"/>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">/**/</script>
  </body>
</html>

尝试本地加载的错误代码：

<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>ReDoc - openapi.json</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <style>
body {
  margin: 0;
  padding: 0;
}
</style>
  </head>
  <body>
    <redoc spec-url="file:///tmp/openapi.json"/>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">/**/</script>
  </body>
</html>

触发的错误信息：

Something went wrong...
process is not defined

Stack trace

resolve@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:301803
resolveExternalRef@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:76499
4182/resolveDocument/<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:77225
4182/r</<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:74930
4182/r<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:74675
resolveDocument@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:77178
3675/t.bundle/<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:33256
3675/r</<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:28947
3675/r<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:28692
3675/t.bundle@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:33035
n@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:579
Mu/</n/e<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:1021
Mu/</n/e<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:837
n@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:1040
Mu/</<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:1261
Mu/</<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:1077
Mu/<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:117:1280
Il@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:488153
53/t.unstable_runWithPriority@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:517125
Wo@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:428837
Rl@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:487616
4448/Cl/<@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:487527
D@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:516186
53/w.port1.onmessage@https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js:8:514909

ReDoc Version: 2.0.0
Commit: 5fb4daa

错误原因

浏览器的同源策略和安全限制禁止直接通过file://协议加载本地文件，ReDoc的浏览器端实现依赖HTTP请求机制获取资源，无法处理本地文件协议的加载逻辑，导致出现Node.js环境变量process未定义的错误。

解决方法

1. 使用本地HTTP服务器（推荐）

将HTML文件和openapi.json放在同一目录下，启动一个简单的本地HTTP服务器，通过HTTP协议访问文件：

Python 3：执行命令 python -m http.server 8000
Node.js：先安装http-server（npm install -g http-server），再执行http-server -p 8000

修改HTML中的spec-url为相对路径：

<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>ReDoc - openapi.json</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <style>
body {
  margin: 0;
  padding: 0;
}
</style>
  </head>
  <body>
    <redoc spec-url="./openapi.json"/>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">/**/</script>
  </body>
</html>

然后在浏览器中访问 http://localhost:8000/你的文件名.html 即可正常加载。

2. 将OpenAPI内容内嵌到HTML中

直接把openapi.json的内容作为spec属性值嵌入到<redoc>标签中，无需单独加载文件：

<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>ReDoc - openapi.json</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <style>
body {
  margin: 0;
  padding: 0;
}
</style>
  </head>
  <body>
    <redoc spec='{"openapi":"3.0.3","info":{"title":"Pet Store","version":"1.0.0"},...}'/>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">/**/</script>
  </body>
</html>

注意：需要将JSON内容转义为单行，或者使用模板字符串（确保引号正确嵌套）。

3. 使用ReDoc CLI生成静态HTML

通过ReDoc的命令行工具直接将openapi.json打包成独立的静态HTML文件，适合离线使用：

安装ReDoc CLI：npm install -g redoc-cli
生成静态文件：redoc-cli bundle openapi.json -o redoc-docs.html
直接打开生成的redoc-docs.html文件即可查看文档。

内容的提问来源于stack exchange，提问作者Aleks Ya