完整指南：几分钟内从源码跑通 Hoppscotch 开源 API 测试工具-开发者社区

完整指南：几分钟内从源码跑通 Hoppscotch 开源 API 测试工具

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

Hoppscotch 是一套开源的 API 开发与测试工具，定位是 Postman、Insomnia 的免费替代：发 HTTP 请求、调 WebSocket、写 GraphQL 查询、管环境变量，Web、桌面、CLI 三种形态都有。这篇文章不讲功能清单，只回答一件事——怎么把它在你自己的机器上跑起来：三条命令起 Web 版、一条命令出生产构建、桌面版和 CI 集成各走哪条路。

先选路线，再动手

同一个仓库里有好几个子项目，先想清楚你要哪种形态，能省掉一半时间：

Web 版（最常用）：浏览器里调试 API，日常开发首选，路径在packages/hoppscotch-common和packages/hoppscotch-selfhost-web
自托管生产版：给团队建一个私有实例，带登录和同步，涉及packages/hoppscotch-backend
桌面版：基于 Tauri 的原生应用，在packages/hoppscotch-desktop
CI 集成：用packages/hoppscotch-cli提供的hopp test命令跑自动化测试

环境自检：先确认三样东西

跑之前检查环境，避免装到一半报错：

pnpm：仓库强制只用 pnpm（根package.json里有preinstall钩子，用 npm 或 yarn 安装会直接报错），项目锁定的版本是 pnpm 10
Node.js 22+：CLI 子项目明确要求 Node >= 22，建议直接上 22
约 1GB 磁盘 + 4GB 内存：monorepo 依赖较多，安装和首次启动都偏吃资源

桌面版额外需要 Rust 工具链，Linux 用户还建议 Ubuntu 22.04 以上（依赖 libwebkit2gtk-4.1），官方推荐 24.04。

三步跑起 Web 版

git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch cd hoppscotch pnpm install

安装过程会触发工作区里每个子包的后置脚本（比如 GraphQL 代码生成），耗时会比一般项目长，属正常现象。

装完启动开发服务器：

pnpm dev

这一条命令会通过pnpm -r do-dev同时拉起前端（hoppscotch-common）和自托管 Web 端（hoppscotch-selfhost-web）的 Vite 服务，带热重载。等终端输出"ready"后，打开它打印的本地地址即可，具体端口以终端为准（Vite 默认一般落在 5173 一带）。

发第一个请求：顶部选 HTTP 方法 → URL 栏填接口地址 → 点 Send，响应、头部、状态码都会显示在下方面板里。后续把常用请求存进 Collections，用 Environments 管理不同环境的变量即可。

打成生产版并自托管

开发验证没问题后，构建静态产物：

pnpm generate

再在根目录用pnpm start起一个静态服务（基于 http-server，默认 3000 端口）做快速预览。要真正给团队用，推荐走 Docker：仓库根目录有docker-compose.yml，一键拉起前端、后端（packages/hoppscotch-backend，NestJS + Prisma + PostgreSQL）整套服务。

一个容易踩的点：桌面版要连接自托管实例时，需要在.env的WHITELISTED_ORIGINS里加上app://形式的前端来源，细节见packages/hoppscotch-desktop/README.md。

桌面版：Tauri 构建原生应用

桌面版是跨平台的 Tauri 应用，除了 Rust 工具链外无特殊依赖。启动开发模式：

cd packages/hoppscotch-desktop pnpm tauri dev

正式版打包用pnpm tauri build（即build:full脚本）。它可以直接连官方云，也可以通过"添加实例"连你自己的自托管地址。

最低系统要求：Windows 10 1803+ / Windows 11 x64、macOS 10.15+（Intel 或 Apple Silicon）、Linux x64 且 GLIBC 2.38+。

把测试搬进 CI：hopp test

不想只靠人点？CLI 子包（@hoppscotch/cli，入口命令hopp）能把你在界面里写好的测试脚本直接跑在流水线里：

npm install -g @hoppscotch/cli hopp test collection.json -e env.json

collection.json是从 Hoppscotch 导出的集合文件，env.json提供环境变量。常用选项还有--server（指向自托管实例）、--reporter-junit（输出 JUnit 报告，方便接 CI 看板）、--delay（请求间隔）。

踩坑速查

npm/yarn 装不上：报错来自only-allow pnpm，换 pnpm 重来
依赖装坏：删掉node_modules后重新pnpm install；锁文件pnpm-lock.yaml别删，它是可复现构建的保证
端口被占：开发服务器被别的进程占着时终端会换端口或报错，按终端输出的实际地址访问
Linux 桌面版白屏/渲染异常：Wayland 下 WebKit 与显卡驱动的已知问题，用WEBKIT_DISABLE_COMPOSITING_MODE=1前缀启动可绕过
老系统报 GLIBC_2.32 not found：桌面版 AppImage 要求 GLIBC 2.38+，升级系统或换新版发行版

往哪走

跑通之后，代码都摆在仓库里：界面逻辑看packages/hoppscotch-common/src/components，后端 GraphQL 接口在packages/hoppscotch-backend/src，CLI 的测试执行逻辑在packages/hoppscotch-cli/src/utils。想改主题、加功能或 fork 一份私有部署，从这几个目录入手最快。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考