Apifox 帮助文档
帮助文档常见问题Apifox 官网私有化部署
开发者中心
  • 开放 API
  • 更新日志
  • Road Map
  • Apifox Markdown
下载
  • 下载 Apifox
  • 下载 IDEA 插件
  • 下载浏览器扩展
  • Apifox Web 版
帮助文档常见问题Apifox 官网私有化部署
开发者中心
  • 开放 API
  • 更新日志
  • Road Map
  • Apifox Markdown
下载
  • 下载 Apifox
  • 下载 IDEA 插件
  • 下载浏览器扩展
  • Apifox Web 版
  1. 解决请求错误
  • 返回首页
  • 常见问题
  • 技术支持概览
  • 为什么参数值中的"+"会被解码成空格？
  • 导入/导出
    • 如何导入接口数据到 Apifox?
    • 如何导入 cURL 到 Apifox？
    • 如何将 Postman 的环境变量迁移到 Apifox？
    • 为什么导出的 API 数量减少了？
    • 为什么导出到 Markdown 和 HTML 时 API 顺序混乱？
    • 如何将文档导出为 PDF/Word？
    • 如何在 Apifox 中导入 Swagger/OpenAPI 时自动将接口分组？
    • postman导入提示错误:URImalformed
  • 发送请求
    • Apifox 是否支持调试 Socket.IO？
    • Apifox 是否支持在 WebSocket 接口中使用前置/后置脚本或者断言？
    • 为什么发送请求的时候，出现"socket hang up"？
    • 为什么发送请求，提示“Invalid URI xxx"?
    • 为什么同一个接口客户端请求成功，在web端调试会出现错误："无法请求地址" ？
    • 接口响应过大时，为什么 Apifox 会报错提示超出 nodejs 字符串最大长度？
    • 解决请求错误
      • 解决 read ECONNRESET 错误
      • 解决 ECONNREFUSED: XXXX 错误
      • 解决 ETIMEDOUT: XXXX 错误
      • 解决 ENOTFOUND: Couldn't resolve host 错误
      • 解决 ENOTFOUND: getaddrinfo ENOTFOUND www 错误
  • 设计 API
    • 可以把响应组件作为默认响应吗？
    • 怎么查看是谁修改了接口？
    • 如何在 Apifox 中批量删除目录？
    • 如何在 Apifox 中批量删除接口？
    • 怎么给接口批量添加或删除 URL 前缀？
    • 如何获取 Apifox 的资源目录 ID？
    • 如何在 URL 路径中使用变量？
    • 如何使用 Apifox 录制接口？
    • 在定义接口响应时，是否允许接口没有任何响应内容？
    • 接口/文档/测试场景不小心删除了怎么办？
    • Apifox 是否支持自定义接口的请求代码？
    • 如何在 Apifox 接口列表中设置显示 接口名称 或 接口 URL？
    • 为什么接口定义的字段在文档中看不到？
    • 如何获取项目ID？
    • 如何快速编辑 JSON 数据结构中的必填字段？
    • 为什么在路径中不支持输入 “#” ？
    • 如果一个字符串属性有多个枚举值，而且在不同地方都用到了，怎么才能保证这个枚举在整个文档里都保持一致？
    • 数组如何配置枚举？
    • 数组如何设置元素的唯一性？
    • form-data 中字段使用 JSON 值
    • 为什么在 Header 添加 Authorization 会有删除线
    • 如何查看最近创建 / 修改的接口？
    • 如何在 Apifox 中的同一字段处理字符串和文件类型？
    • 接口保存提示 “参数字段长度超过限制”，但未发现单个参数过长，如何解决？
    • 如果同时发送 file 和 json（body请求参数又要有实体类又要有文件）
    • 接口参数值如何设置为 null
  • 调试 API
    • 为什么同样的请求在其它工具（比如 Postman）里能正常工作，但在 Apifox 里却不行？
    • 怎么把其它工具的环境迁移到Apifox？
    • 怎么在 Apifox 里用脚本做断言？
    • JSONPath 只能提取数组，那在 Apifox 里怎么从数组中提取单个元素呢？
    • 在 Apifox 中，不同环境有不同的数据库连接，怎么配置数据库操作？
    • 如何在目录级别添加 header 参数？
    • 如何在自定义脚本中获取服务 baseURL？
    • 如何在 Apifox 自定义脚本中生成动态值？
    • 如何在 Apifox 中查看原始报文？
    • 如何在 Apifox 脚本中发起异步请求？
    • 控制台打印内容大小限制是多少？为什么打印大文件会报错？
    • 如何在接口请求时上传文件？
    • Apifox 中如何设置请求超时时间？
    • 如何批量修改 Header 的 User-Agent 字段
    • 接口带上了非预期的 Cookie 怎么处理？
    • 使用 Windows 版本连接 DB2 数据库时报错怎么解决？
    • 使用 Apifox 连接 Oracle 数据库报错 NJS-045?
    • 为什么 curl 请求正常返回 200，但在 Apifox 中请求却返回 400？
    • 为什么直接使用 Apifox 生成的 curl 运行报 “URL using bad/illegal format or missing URL“ ？
    • 为什么在 Apifox 上传文件，后台接收不到？
    • 接口签名使用 AES-GCM 加密
    • 前置脚本如何使用 SHA256withRSA 加密？
    • 如何将 Apifox 项目导入到离线空间里？
    • Dubbo 接口调试时出现 "The socket was closed.(address:address=>bolt://{ip})" 错误，如何解决？
    • 为什么 WebSocket 在 web 端连接正常，在客户端报“1006 Abnormal Closure“？
    • Apifox 是否支持 STOMP 协议的 WebSocket 连接？
    • 发送请求失败 “Error: getaddrinfo ENOTFOUND xxx.xxx.xxx.xxx” 的原因及排查方法
    • 为什么网络正常，访问 Apifox 提示“连接 Apifox 服务器出错，请检查网络是否异常”？
    • Web端运行接口时，报错提示 Get "http://localhost:3000/test": dial tcp [::1]:3000: connect: connedtion refused
    • 为什么Web端发送请求正常，客户端发送请求，出现“read ECONNRESET”？
    • 为什么使用 Web 网页端，通过浏览器插件请求 Ollama 部署的大模型会提示 403？
    • 为什么在 WEB 端中修改 Referer 请求头无效？
    • 接口返回的是 Protobuf 数据，如何正常查看？
    • 接口请求中 Header 携带 Authorization 参数不生效问题
    • 为什么点击 Body 的自动生成 点击不生效，不更新参数值？
    • 如何通过本地解压文件的方式添加 Apifox 浏览器插件？
    • 如何在文件修改后，接口直接读取修改的文件（本地文件路径以变量存储）
    • Socket 如何使用 GBK 格式发送数据？
  • Mock 数据
    • Apifox支持 Mock WebSocket 接口吗？
    • 为什么浏览器请求 Mock 接口没有返回内容？
    • Mock 数组数据时，如何让生成的数据不重复？
  • 自动化测试
    • 为什么测试场景 Apifox 客户端运行没问题，但在 Apifox CLI 或 Runner 中运行时却出错了？
    • 为什么无法成功引用前置步骤数据？
    • 在性能测试中怎么查看实际的请求和响应？
    • 在 Apifox 中怎么导出性能测试报告？
    • 如何使用数据库查询得到的数据循环传参给接口运行?
    • 如何解决 "Error: unable to verify the first certificate on runner" 错误？
    • 为什么在 CLI 执行完生成的测试报告，使用 Apifox 客户端查看报告每个 case 的详情都看不到呢？
    • 如何在 Apifox Web 版设置通用 Runner 的服务器 Host？
    • 接口参数是一个上传文件在 Runner、CLI 中找不到怎么办？
    • 当 Runner 发生问题了，如何查询 Runner 日志用以定位？
    • 如何查看 runner 版本号？
    • 使用 Runner 运行测试场景报错，报告提示"unsafe legacy renegotiation disabled"?
    • 用自托管 Runner 执行了任务， 服务器有对应测试报告生成吗？
    • 为什么linux系统在安装cli后不能直接使用
    • 为什么测试步骤同步不了接口的参数值？
    • 为什么接口用例改了，测试步骤没有自动同步？
    • 如何在 PowerShell 中运行 Apifox CLI 命令
    • 可以给测试场景下的请求添加统一的前后置操作吗？
    • 自动化测试中如何让动态值在单次测试中保持一致？
    • 如何在持续集成中选择多个测试场景一起运行？
    • 使用 CI/CD 是否支持通知
    • 为什么使用数据库步骤查看时间数据时，与 Navicat 之类的工具显示格式不一致？
  • 发布 API 文档
    • 怎么在发布的文档中隐藏所有 Apifox 的元素（Logo、按钮等）？
    • 当在 Apifox 中更新文档内容时，已发布的线上 API 文档会跟着改变吗？
    • 自定义域名一直显示未生效怎么办？
    • 如何检查 CNAME 配置是否正确？
    • Apifox 自定义域名的 SSL 证书生成失败怎么办？
    • Apifox 发布文档/快捷分享中，如何让使用者修改请求的 Base URL ？
    • 如何将 Apifox 发布文档复制到自己的项目中？
    • 如何在 Apifox 在线文档中共享 Header（如 Token）？
    • 在线文档中调试 http 接口时报错"Mixed Content request rejected"？
    • 当发布文档中图片显示“该图片来自其他私有项目,不可访问”,如何处理
  • 迭代分支
    • 怎么访问迭代分支？
  • 管理中心
    • Apifox 项目、团队和组织的区别
    • 如何为 Apifox 添加白名单？
    • 如何为 Apifox 中的团队配置「IP 允许访问名单」？
    • 如何设置项目权限？
    • 如何设置团队权限
    • 如何邀请已加入团队的成员进入项目？
  • IDEA 插件
    • 为什么通过 idea 插件导入的数据模型名称带有《》？
    • Apifox IDEA 插件可以上传某个 controller 里的指定接口么？
    • 为什么 IDEA 上更新字段内容后推送到 Apifox 内容没更新？
    • 在 IDEA 上如何标记泛型？
  • Markdown 相关
    • 如何在 Apifox 的卡片组件中链接到项目内的文档或接口？
    • 如何在 Markdown 文档中插入项目内接口/文档/数据模型/目录？
    • 怎么在 Apifox 的 Markdown 中使用透明背景图片？
    • 为什么 Markdown 文档中使用多个 $ 时部分内容没有正确显示？
    • 如何在 Apifox 的 Markdown 中编写流程图？
    • 如何控制 Markdown 表格的列宽？
  • 收费与部署
    • Apifox 是否收费？
    • 数据是存储在本地还是云端？可否离线使用？可否私有化部署？
    • 购买【商业专业版】1年，使用半年后升级到【商业旗舰版】，如何计费？
  • Web 端与客户端
    • Apifox alpha 版下载
    • Web 端与客户端有何区别？
    • Web 端与客户端数据不同步如何处理？
    • 为什么下载时会跳到百度网盘或天翼网盘？
    • ApifoxAppAgent 进程的作用是什么？
    • 为何 Apifox 启动会有多个 Helper 进程？
    • Apifox 闪退、白屏怎么办？
    • Apifox 如何打开开发者工具？
    • Apifox 支持 win7 吗?
    • Win 系统自动更新后打不开可能是什么原因？
    • 为什么 Windows 安装新版本后打开还是旧版本？
    • 微信、手机号提示已经被绑定了怎么办？
    • 为什么安装 Apifox 后启动提示"无法定位程序输入点DiscardVirtualMemory 于动态链接库KERNEL32.dll"
    • Ubuntu 24 无法启动 Apifox，如何处理？
  • MCP Server
    • Apifox 新增接口目录后，MCP 没有获取到新的目录?
    • Apifox MCP 为什么会识别不到本地文档的 API 接口?
    • 内网私有部署的大模型，能够直接用 apifox 的 mcp 嘛？
    • 如何让 Apifox MCP Server 的 Tools 名称后面不添加随机字符串
  1. 解决请求错误

解决 ENOTFOUND: Couldn't resolve host 错误

ENOTFOUND: Couldn't resolve host 错误表示系统无法将你请求的域名或主机名转换为对应的 IP 地址。这是网络请求的第一个关键步骤——域名解析失败了。

错误原因#

这个错误主要和 DNS（域名解析系统） 有关，而不是服务器是否开启的问题。

1. 域名拼写或格式错误#

域名拼写错误： 请求 URL 中的域名拼写有误，比如缺少/，或者多了一个/，导致 DNS 找不到对应的记录。
URL 格式问题： 缺少 http:// 或 https://。

2. 本地 DNS 或 Hosts 文件问题#

DNS 缓存污染： 你的电脑或路由器缓存了错误的 DNS 解析记录。
Hosts 文件干扰： 你的本地 hosts 文件（用于本地覆盖 DNS 解析）中包含了错误的或过时的域名解析条目。

3. 网络环境或防火墙限制#

网络连接中断： 你的设备没有连接到互联网，或网络不稳定。
DNS 服务器故障： 你的网络配置使用的 DNS 服务器（如路由器或 ISP 的 DNS）出现故障或无法访问。
VPN/代理干扰： 正在使用的 VPN 或代理 服务配置错误，干扰了正常的 DNS 解析。
防火墙限制： 你的本地防火墙或安全软件阻止了 DNS 查询请求（通常是 UDP 53 端口）。

解决方法#

你可以按照以下步骤逐一排查和解决 ENOTFOUND: Couldn't resolve host 错误：

1. 安装插件或使用桌面版#

如果你使用的是 Web 版，请安装 浏览器扩展 后再发送请求，也可以直接使用 桌面版（推荐）。

2. 检查和修正域名/URL#

核对域名： 仔细检查你在 Apifox 中使用的完整 URL 或 前置 URL（Base URL）中的域名拼写是否完全正确，是否缺少了/，或者多了一个/。
例如，确保你输入的是 api.example.com 而不是 api.exampel.com。
检查 URL 格式： 确保 URL 包含正确的协议（http:// 或 https://）。
若接口的前置 URL 含有环境变量，需要检查变量的值是否错误。

3. 刷新和检查本地解析#

浏览器测试： 尝试在你的浏览器中直接访问这个 URL。如果浏览器也无法访问，说明问题出在你的电脑或网络上。
刷新 DNS 缓存：
Windows: 打开命令提示符（CMD），输入 ipconfig /flushdns 并回车。
macOS: 打开终端，输入 sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder 并回车。
检查 Hosts 文件：
检查你的本地 hosts 文件
Windows 路径：C:\Windows\System32\drivers\etc\hosts
macOS / Linux 路径： /etc/hosts
删除或注释掉（在行首加 #）任何与你请求的域名相关的解析记录，然后保存文件。

4. 检查网络和代理配置#

更换 DNS： 暂时将你的网络 DNS 设置更改为公共 DNS（例如 Google DNS: 8.8.8.8 或 Ali DNS: 223.5.5.5），然后再次尝试请求。
检查 VPN/代理： 如果你正在使用 VPN 或代理，请：
尝试关闭 VPN/代理 后发送请求。
如果需要使用代理，请进入 Apifox 的 “设置 -> 网络代理” 页面，确保代理配置信息是完全正确的。
image.png
重启网络设备： 尝试重启你的路由器和调制解调器，清除潜在的网络问题。
上一页
解决 ETIMEDOUT: XXXX 错误
下一页
解决 ENOTFOUND: getaddrinfo ENOTFOUND www 错误
Built with