简介这是一份面向开发与测试人员的开源API调试工具源码包基于Node.js与Vue构建用于接口联调、请求验证与问题排查。其界面直观、上手成本低支持多种HTTP请求方法可在前后端分离项目中承担快速验证接口和优化调用流程的角色适合具备一定前端基础、需要自行部署或二次开发的开发者。压缩包共1376个文件、约5.28MB以592个TypeScript文件与211个Vue单文件组件为主体构成前端页面与核心逻辑另有203个GraphQL定义、120个JSON配置以及SVG图标、SCSS样式等资源。包内还附有Dockerfile、Caddyfile与yml部署配置自托管与数据层配置相对完整目录结构便于按模块检索阅读。目前已有914人学习下载可作为了解API调试工具工程化架构的参考。1. 起手先看场景为什么很多人把 hoppscotch 当日常调试入口第一次打开 hoppscotch 的人反馈基本是同一句怎么这么快。作为一个跑在浏览器里的开源 API 调试工具它把入口压到地址栏——不用等安装包解压不用注册点开就能发请求。这个差异在真实工作里很值钱临时要验一个第三方回调地址、要在同事机器上复现一个 401、要在手机上瞄一眼接口返回体积小和启动快就是绝对优势。但它并不是「阉割版客户端」环境变量、集合分层、预请求脚本、测试断言、CLI 进流水线这套工程化链路是齐的。下面按我实际落地的顺序拆先定部署形态再讲变量和集合怎么组织然后写断言最后把几个反复踩的坑摊开。2. 部署形态怎么选Web、桌面、自托管三张牌的边界选型这一步如果偷懒后面全是补偿动作。我见过最常见的错误是团队在内网做联调图省事全用 Web 版结果每个请求都卡在跨域上然后花两天去调后端 CORS 配置——其实换成桌面版五分钟就绕过去了。反过来有人一上来就自托管折腾完发现团队根本不需要共享集合纯属给自己加运维负担。2.1 三种形态各自解决什么问题先把能力边界摆清楚再谈选谁。形态数据存在哪跨域处理适合的场景明显短板Web 版浏览器浏览器本地存储 / IndexedDB受同源策略约束需要代理或扩展快速验证、临时调试、换机即用私有网络里的服务需要额外代理配置桌面版本机应用数据目录原生 HTTP 客户端天然不受同源策略限制内网联调、需要读本地证书、大响应体需要分发安装包多设备同步靠手动导出自托管自己的数据库同 Web 版但代理服务可以自己控制团队共享集合与环境、数据不出内网要维护数据库、对象存储、邮件服务选型逻辑其实就三个问句请求目标是不是在浏览器够不着的内网团队是不是需要一份公共的集合而不是各存各的能不能接受多养一套有状态的服務三问两「是」就上自托管只有第一问「是」就用桌面版全是「否」就老老实实 Web 版加扩展。这里有个容易被忽略的点自托管不等于「什么都自动有了」。社区版和商业版在组织权限、细粒度角色、审计这类能力上有差异落地前先确认你要的功能属于哪一档别部署完了才发现想要的协作模式不在里面那时候迁移成本比重新选型还高。2.2 浏览器端跑通第一条请求代理和拦截器别搞混Web 版第一次发请求就报 CORS是绝大多数人的第一课。原因不复杂请求是从页面脚本发出去的浏览器按同源策略拦截响应服务端就算返回了数据前端也读不到。解决办法有两条路效果不一样。第一条是装浏览器扩展做拦截。扩展有权限直接发请求绕开页面的同源限制请求实际是从扩展的上下文出去的。装完之后要在扩展的设置里把当前站点加进允许列表否则它不接管。第二条是走代理模式把请求发给一个代理服务由服务端转发。自托管的时候这个代理可以自己部署等于把控制权拿回来了。操作顺序我一般是这样先在设置里确认代理开关是打开的再看扩展图标是不是处于接管状态最后用一条最无害的请求试水比如拿一个公开的 Echo 接口回显请求头。回显能看到自己加的 header说明链路通了回显是空的或者报网络错误说明请求根本没出去问题在代理这一层不在目标服务。# 用 curl 做对照实验先确认服务本身是通的排除后端问题 curl -i -X POST https://httpbin.org/anything \ -H Content-Type: application/json \ -H X-Trace-Id: probe-001 \ -d {hello:world}这条命令的价值在于建立基准。如果 curl 通、工具不通问题百分之百在客户端的代理或跨域链路如果 curl 也不通那就别在工具上耗时间了去查网络和目标服务。我习惯把这个对照做成肌肉记忆能省掉大量「到底是哪一层的问题」的猜测。还有一类隐性失败请求发出去了服务端日志也有记录但工具里显示失败。这种多半是预检请求被拦——浏览器在发带自定义 header 的跨域请求前会先发一个 OPTIONS服务端如果没正确响应这个方法正式请求压根不会发。看浏览器开发者工具的网络面板如果只看到 OPTIONS 而没有后续请求就是这个原因。2.3 自托管起一套真正要改的只有那几个变量自托管的价值在于集合和环境是团队共享的资产不是某个人浏览器里的私货。部署方式上容器编排是最省事的路子官方提供的编排文件拉下来把几个必须自己决定的变量改掉就能起。services: db: image: postgres:16 environment: POSTGRES_USER: hoppscotch POSTGRES_PASSWORD: change-this-db-pass POSTGRES_DB: hoppscotch volumes: - pgdata:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:7 restart: unless-stopped backend: image: hoppscotch/hoppscotch-backend:latest depends_on: - db - redis environment: # 数据库连接串用户名密码要和上面 db 服务保持一致 DATABASE_URL: postgresql://hoppscotch:change-this-db-passdb:5432/hoppscotch # 三个密钥必须自己生成不要用示例值换了之后已签发的会话全部失效 JWT_SECRET: replace-with-a-long-random-string TOKEN_SALT: replace-with-another-random-string SESSION_SECRET: replace-with-a-third-random-string REDIS_URL: redis://redis:6379 # 邮件配置邀请成员、找回密码都依赖它不配就只能自己手动建账号 MAILER_SMTP_URL: smtps://user:passsmtp.example.com:465 MAILER_ADDRESS_FROM: no-replyexample.com restart: unless-stopped frontend: image: hoppscotch/hoppscotch-frontend:latest depends_on: - backend environment: # 这四个地址是浏览器实际访问的地址写 localhost 只能本机用 VITE_BASE_URL: http://localhost:3000 VITE_BACKEND_GQL_URL: http://localhost:3170/graphql VITE_BACKEND_WS_URL: ws://localhost:3170/graphql VITE_BACKEND_API_URL: http://localhost:3170/v1 VITE_SHORTCODE_BASE_URL: http://localhost:3000 ports: - 3000:3000 restart: unless-stopped volumes: pgdata:这份编排里注释掉的都是实战中必须动手改的位置。参数说明几个关键项DATABASE_URL里的主机名要用服务名db而不是 localhost容器之间走的是内部网络。JWT_SECRET、TOKEN_SALT、SESSION_SECRET三个值要一次生成好并妥善保存中途换掉会导致所有已登录会话失效用户全部被踢下线——这事发生在生产环境上就是个事故。VITE_*系列是编译进前端产物的地址改完必须重建前端容器才生效只重启不重建是没用的这是非常经典的一个坑。部署完之后第一件事不是发请求是把反代配好并确认访问地址一致。前端里写的VITE_BASE_URL和你浏览器地址栏里的域名端口不一致登录后刷新就会掉线因为 cookie 和回调地址对不上。我一般会用一个明确的公网或内网域名从头到尾不出现 localhost能规避一大半奇怪问题。3. 环境变量与集合把一次性请求变成可迁移的工程资产工具用得不顺八成不是功能不够是组织方式不对。一个项目几十个接口如果每条请求都把主机名、token 手打一遍换个环境就要改几十处改漏一处就是半天排查。环境变量的意义就是把「会变的东西」抽出来让请求本身只描述协议和路径。3.1 变量引用的三层结构与优先级hoppscotch 的变量大致分三层全局变量对所有环境和所有集合生效环境变量挂在某一个环境上切换环境就切换一整套值请求局部则在单条请求里覆盖。引用语法是双尖括号包裹变量名形如host。优先级的直觉是「越靠近请求的越优先」请求局部覆盖环境变量环境变量覆盖全局变量。这个顺序很重要因为它决定了你怎么做灰度或者临时覆盖。比如host在环境里配成测试环境地址某条请求要打预发就在这条请求的局部变量里改成预发地址不用动环境也不影响别的请求。我见过的失败模式是把 token 配在全局变量里然后所有环境共用。切到测试环境后 token 还是生产环境的请求全部 401而且错误信息看不出是 token 的问题特别浪费时间。正确做法是把鉴权相关的值全部放进对应环境全局变量只放那些真正跨环境不变的东西比如客户端标识。环境配置里还有一种特殊环境值不落库、不进导出文件适合放密钥。什么时候用它当你要把环境导出给同事或者提交到仓库时。普通环境导出就是明文一条cat env.json就能看到所有 token这类事故我见过不止一次。3.2 集合的三层结构与命名约定集合是文件夹文件夹里放请求最多三层这个深度基本够用。关键是命名因为搜索和导出之后全靠名字认。我的约定是按业务域做第一层按操作做第二层请求名直接写「动词 资源 关键条件」。比如订单域 / 查询 / 按用户查订单-分页。不要用「测试1」「新接口」这种临时名字当时省两秒两周后自己都不认识。集合里还可以写描述把前置条件、依赖的初始化数据写进去这东西在你交接或者半年后回看时价值极高。另一个习惯是给每个集合固定放一条「健康检查」请求打的是最轻的接口用途是快速验证环境和网络。联调出问题时先跑它通了说明链路没问题问题在具体接口不通就直接查环境和网络省掉大量试错。3.3 导入导出和外部格式互通的真实边界工具之间迁移是常态hoppscotch 支持导入若干常见格式也支持导入 curl 命令。能力是有的但边界要清楚。导入 curl 是最常用的入口。我一般这么干# 从浏览器开发者工具里复制出来的请求先落成一行能跑的命令 curl https://api.example.com/v2/orders?page1size20 \ -H Authorization: Bearer eyJhbGciOi... \ -H Accept: application/json把这段粘进导入框它会解析成一条带方法、URL、header 的请求。注意几个解析边界单引号在 Windows 终端和 Linux 终端行为不同粘之前先确认引号形态-d后面的 JSON 如果是多行部分解析器会截断建议压成一行再导入文件上传的-F参数带本地路径导入后路径会失效需要手动重新选文件。导入集合格式时最常见的失真不是请求丢了是变量丢了。外部工具用双大括号引用变量这里的语法是双尖括号导入过程一般会做转换但环境本身不会跟着走需要单独导入环境文件。导入完第一件事是切到每条请求上看变量是不是都被高亮识别了——没高亮的说明是死引用运行时会把字面量原样发出去服务端收到的可能是token这种字符串报错信息往往很迷惑。从接口描述文件导入是另一条路。把 OpenAPI 文档丢进去能批量生成请求骨架适合在项目初期快速铺开。但生成的请求只是骨架鉴权头、业务必需的公共参数、签名逻辑都不会自动带上这些要靠环境变量和预请求脚本补齐。别指望一键导入就能跑通把它当成省掉手打路径的工具就好。4. 测试脚本与断言让请求自己证明自己是对的手工看返回值判断对错只能验证一次。接口一改你得把所有请求重跑一遍用眼睛看。脚本化的价值就在这把「我认为这样算对」写成断言之后每次运行机器替你看。4.1 预请求脚本与测试脚本的执行时机差异两个脚本挂在同一条请求上但跑的位置完全不同。预请求脚本在请求发出之前执行能改请求头、改请求体、设置变量测试脚本在响应回来之后执行能读状态码、读响应体、做断言、把值写回变量。这个顺序决定的典型用法是这样的预请求脚本负责「准备」——算时间戳、拼签名、生成幂等键测试脚本负责「验证」——断言状态码、断言字段类型、把返回的 id 存下来给后续请求用。有个细节容易翻车预请求脚本里改了请求头页面上显示的请求头预览不会实时更新你得靠实际发出的请求去验证。我一般会在预请求脚本最后把关键的 header 写进环境变量跑完之后看一眼变量值确认拼出来的东西是不是我想要的。这个动作花三秒钟能省掉半小时的「为什么服务端说签名不对」。时间戳和签名类逻辑还有个坑脚本里拿到的当前时间和你本地时区有关有些服务端校验时间戳时按 UTC 算偏差几分钟就拒绝。稳妥做法是在预请求脚本里显式按 UTC 生成或者干脆把时间源做成一个可以从环境变量覆盖的值方便复现问题。4.2 断言的基本写法和几条实用断言断言 API 挂在pw对象上用起来是链式的取值、挂期望、比对。下面这段是我在几乎所有集合里都会放的样板。// 状态码必须符合预期先卡第一道关 pw.expect(pw.response.status).toBe(200); // 业务层返回体里通常有个 code 字段也要断言别只看 HTTP 状态 const body pw.response.body; pw.expect(body.code).toBe(0); // 结构断言字段存在且类型正确防止后端把数组改成对象还没人发现 pw.expect(Array.isArray(body.data.list)).toBe(true); pw.expect(typeof body.data.total).toBe(number); // 值与值之间的关系断言分页返回的条数不能超过请求的 size pw.expect(body.data.list.length 20).toBe(true); // 把关键 id 回写到变量供后续请求引用 pw.env.set(last_order_id, body.data.list[0].id);逐行说下逻辑。第一条断 HTTP 状态是最外层契约200 之外的任何值都直接判失败这样出错时定位最快。第二条断业务码很多服务端 HTTP 永远 200错误藏在返回体里只断状态码等于什么都没断。第三、四条断结构这是一类特别有价值的断言后端把字段类型悄悄改了、把数组包了一层对象前端不报错但渲染会空人眼看返回值经常发现不了断言能。第五条断业务规则比大小、比范围、比顺序这是把需求文档变成可执行代码的地方。最后一条是变量回流下文细说。写断言有个度的问题。不是每个字段都要断抓住三类就够决定请求是否成功的状态码、业务码、下游依赖的id、token、游标、容易静默变化的类型、数组长度。全字段断言的结果是接口一加字段就红一片最后没人看结果等于没写。4.3 变量回流把上一步的响应喂给下一步这是脚本能力里最实用的一块。典型场景先登录拿 token后续所有请求带上它。手工复制粘贴 token 的问题是它有过期时间每次过期都要重来一遍。// 测试脚本里登录成功后把 token 写进当前环境 const res pw.response.body; pw.expect(res.access_token).toBeTruthy(); pw.env.set(access_token, res.access_token); pw.env.set(refresh_token, res.refresh_token); // 顺手记一下过期时间方便判断要不要重新登录 pw.env.set(token_expire_at, String(Date.now() res.expires_in * 1000));在后续请求的鉴权头里写Bearer access_token变量就自动替换了。这里有个必须说清的边界pw.env.set写入的是运行时的变量上下文只有连续执行的场景集合批量运行、CLI 执行才会把值传给下一条请求。你在页面上单条点「发送」那条请求跑完上下文就结束了下一条点开还是旧值。很多人第一次用这个功能就是在这里翻车以为变量没写进去其实是执行模式不对。要验证回流是否生效最直接的办法是跑整个集合而不是单条请求跑完看执行结果里每条请求的实际请求头。如果第二条请求的头里是完整的 token 而不是占位符说明链路通了。这一步建议在写脚本的当下就做一次别等到 CI 里才发现。5. 避坑与排查五条让我改掉习惯的现场记录下面这几条都是真金白银换来的每条按现象、原因、解决写遇到对应症状可以直接照着排。5.1 开了代理还是跨域报错现象浏览器控制台里持续报跨域请求状态显示失败但同一个地址用 curl 明明能通。切到扩展接管状态依然没变化。原因通常有两层。一层是扩展没有接管当前站点扩展的权限是按站点授予的换了域名或者从 http 切到 https 都要重新授权。另一层是预检请求被拦请求带了自定义 header 或者非简单方法的 body浏览器先发 OPTIONS服务端没正确响应Access-Control-Allow-Headers正式请求根本不会发出。解决先看网络面板里有没有 OPTIONS 记录有就说明是预检问题去后端补响应头别在客户端绕。没有 OPTIONS 也没正式请求说明请求没出去检查扩展的站点授权列表和代理开关。还有一种情况是公司网络有出口代理工具的代理设置和系统代理叠加请求被转了两次表现是超时而不是跨域这种就看工具的连接日志有没有出站记录。5.2 脚本里设的变量下一条请求读不到现象登录请求的测试脚本里明明写了pw.env.set(access_token, ...)下一条请求的鉴权头还是空值或者字面量占位符。原因单条发送模式下没有跨请求的执行上下文。变量的生命周期绑定在一次运行上单点发送就是一次运行一条请求写完就结束。解决改用集合或文件夹级的批量运行让多条请求在同一个上下文里顺序执行。跑之前确认执行顺序对——文件夹里的顺序就是执行顺序登录请求必须排在前面必要时用文件夹把「前置依赖」和「业务用例」分开。另一个易错点是变量名拼写access_token和accessToken在这是两个变量不会报错只会静默取不到值建议变量名统一用下划线风格。5.3 导入外部集合后大面积失效现象集合导入成功请求数量也对但跑起来大量 404 和 401请求体是空的。原因环境没有一起导入是最常见的其次是引用语法转换不完全部分嵌套变量没被识别第三是表单类型的请求里带本地文件路径导入后路径无效整个请求体被判为空。解决分三步核对。第一步导入环境文件导入后逐条请求看变量是否被高亮识别没高亮的说明是死引用手动改。第二步挑三条代表性请求一个 GET、一个 JSON POST、一个表单上传单独跑确认请求体形态对不对。第三步检查表单类请求的文件字段重新选一次本地文件顺带确认字段类型是文件还是文本。做完这三步再批量跑比一口气跑完看几十条失败要快得多。5.4 自托管登录后刷新就掉线现象自托管部署完成能登录也能正常用但刷新页面就退出登录或者邀请成员时邮件一直收不到。原因地址不一致。前端构建时写进去的地址和你实际访问的地址不同——比如构建时是 localhost实际用内网 IP 访问或者前面挂了反向代理但没透传原始协议头导致回调地址和 cookie 的域对不上。邮件问题则是 SMTP 配置缺失或者端口被出口策略拦了。解决把所有对外地址统一成一个值反代上配置透传原始 Host 和协议头改完重建前端容器而不是重启。邮件这块先用一个能收信的外部邮箱做验证确认发得出去再换成正式地址端口优先试 465 的加密方式587 的 STARTTLS 在某些网络环境里更容易被拦。5.5 大响应体把页面拖死现象请求一个返回几十兆 JSON 的接口标签页直接卡住十几秒甚至提示页面无响应。原因响应体要完整解析并在界面上渲染成可展开的树节点数量上万时前端渲染压力非常大这不是网络慢是渲染慢。解决临时看结构的话在请求里加字段筛选参数让服务端少返回必须看全量的话用命令行跑同一条请求把结果落到文件里再用其他工具分析。日常调试养成习惯先在请求上限定分页大小和返回字段别一上来就拉全量。这个坑在学生作业和内部工具里特别常见因为大家默认「返回越多越好」实际是给自己找麻烦。6. 最后一步用 CLI 把集合塞进流水线手工点集合运行只能证明「我刚才跑通了」证明不了「明天改了代码它还通」。真正的闭环是把集合导出在流水线里用命令行跑失败就阻断发布。导出集合和环境各一个 JSON 文件然后# 安装命令行工具全局装流水线里也可以用 npx 免安装 npm install -g hoppscotch/cli # 跑整个集合-e 指定环境文件--env 指定环境名-r 输出报告 hopp test ./collections/order-service.json \ -e ./environments/staging.json \ --env Staging \ -r json \ --reporter-export ./report.json参数上重点说三个。--env指定用环境文件里的哪一套变量一个文件里可以放多套环境流水线按分支切换就行不用维护多份文件。-r是报告格式接 CI 平台的时候用对应格式能让失败用例直接显示在流水线界面上。--reporter-export把结果落盘排查历史失败时非常有用比翻控制台日志强。退出码是判断依据有断言失败就返回非零流水线自然就红了不需要额外写判断逻辑。有一件事我建议你提前在本地做一遍把导出的集合和环境提交到仓库之前先把里面的密钥清掉改用流水线的环境变量注入。这个动作看起来多余但我见过太多次把生产 token 提交进仓库的事故清理历史提交的代价远大于事先多花五分钟。描述文件里如果出现了不该出现的字段检查一下是不是有环境没走特殊环境类型。从那以后我每次导出集合都会先跑一遍grep找 token 关键字确认干净了再提交这个习惯救过我至少两次。希望帮到你。本文还有配套的精品资源点击获取