从 clone 到跑起来：Hoppscotch 开源 API 测试平台新手完整指南-平芜编程栈

从 clone 到跑起来：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 等各类请求。全文按"拿到仓库 → 环境准备 → 第一次运行 → 二次定制"的时间线展开，跟着做大约十几分钟就能在本地看到界面。

拿到仓库后先看哪里

仓库根目录只有一个packages/源码目录加一批部署脚本，没有独立的docs或tests顶层目录，测试分散在各包内。你真正会碰到的就是这几个入口：

根package.json：所有脚本的总开关，开发、构建、测试都从这里发起
docker-compose.yml：自托管部署的唯一 Docker 入口，内置 PostgreSQL
devenv.nix：用 Nix 管理开发环境的可选配置
packages/hoppscotch-common/：网页端主应用（Vue 3 + Vite）
packages/hoppscotch-backend/：NestJS + Prisma 写的后端，负责账号、团队、集合同步
packages/hoppscotch-cli/：命令行测试工具
packages/hoppscotch-selfhost-web/：自托管时承载静态资源和代理的 Web 服务

clone 命令（如需从镜像获取）：

git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch.git

环境准备：pnpm 版本必须对

项目是 pnpm workspace（见 pnpm-workspace.yaml），根package.json声明了preinstall钩子，只允许用 pnpm 安装，用 npm/yarn 会直接报错。

两个硬性要求：

pnpm 版本：以根package.json里的packageManager字段为准（当前为pnpm@10.33.4），版本不一致时可用corepack enable让 Node 自动匹配
Node 版本：官方 Nix 环境锁定的是 Node 22（见 devenv.nix 里的nodejs_22），建议本地也装 22 及以上

本地启动网页端开发服务

装依赖并起前端：

pnpm install pnpm dev

pnpm dev实际执行的是pnpm -r do-dev，会并行拉起各包的开发服务，网页端由 packages/hoppscotch-common/ 的 Vite 服务承载，起来后浏览器访问它打印的地址即可。具体脚本定义以各包package.json的scripts为准。

其他常用脚本（都在根package.json里）：

pnpm generate：构建全部包的生产产物
pnpm start：用 http-server 托管packages/hoppscotch-selfhost-web/dist，端口 3000（需先执行pnpm generate）
pnpm test/pnpm lint/pnpm typecheck：全仓库的测试、检查

一条命令部署自托管版

想直接体验"带账号、团队、云同步"的完整版本，用仓库自带的 Docker Compose 最省事。docker-compose.yml 用 profiles 组织了多种部署方式，推荐默认的全合一模式：

docker compose --profile default up

它会同时启动 AIO 容器（Web 应用 + 后端 + 管理后台）、PostgreSQL 15 和一个自动执行prisma migrate deploy的迁移服务。启动后常用端口：

端口	服务
3000	Hoppscotch 主应用
3100	自托管管理后台
3170	后端 API

不想带数据库时换成--profile default-no-db，改用外部 Postgres。部署拓扑长这样：

环境变量改哪里

所有服务都读取仓库根目录的.env文件（docker-compose.yml里每个服务都写了env_file: ./.env）。这个文件被.gitignore忽略，仓库不提供模板，需要你自己创建。最常改的一项：

DATABASE_URL=postgresql://postgres:你的密码@localhost:5432/hoppscotch?connect_timeout=300

注意 compose 文件里数据库的默认密码是testpass，生产环境务必改掉。后端读取哪些环境变量，可以直接查 packages/hoppscotch-backend/src/ 的源码；数据库结构变更统一放在packages/hoppscotch-backend/prisma/migrations/目录。

二次定制：改主题、加翻译、接 CLI

换语言：界面文案在 packages/hoppscotch-common/locales/，每种语言一个 JSON 文件；多语言贡献流程见 TRANSLATIONS.md
换主题：主题配色在 packages/hoppscotch-common/assets/themes/，基础样式用 Tailwind（根目录 tailwind.config.ts）+ SCSS 组织
命令化测试：packages/hoppscotch-cli/提供 CLI，配合集合文件做自动化测试，用法见该包内的 README.md
桌面端：packages/hoppscotch-desktop/基于 Tauri，可以指向你自己部署的实例，实现数据完全离线

常见问题速查

pnpm install报 only-allow 错误：你在用 npm/yarn 安装，换成 pnpm 再试
界面连不上后端：确认后端服务在跑（Docker 模式下 3170 端口），并核对.env里的地址配置
Prisma 迁移报错：默认流程里迁移服务会先等数据库健康检查通过再执行，手动操作时注意docker compose --profile database up单独拉起数据库先

想深入功能细节，官方文档站有完整说明；代码层面则以上述各包的package.jsonscripts 和源码为准。

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