企业官网建设流程全解析

如何从源码构建自托管的 Hoppscotch Desktop 应用

【免费下载链接】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 部署在内网或自己的服务器上，直接使用官方下载或 Homebrew 安装的 Hoppscotch Desktop 客户端并不是唯一路径——packages/hoppscotch-desktop/README.md 的 "Building and Self-Hosting Hoppscotch Desktop" 一节给出了从源码本地构建的完整流程，构建出的桌面应用可以直接连接你自己的自托管 Hoppscotch 实例。整条路径共四步：构建自托管 Web 前端、编译webapp-bundler、打包 Web 应用为 bundle、运行桌面应用。需要注意：Hoppscotch Desktop App 目前仍标注为ALPHA阶段（见 README 标题），应用基于 Tauri V2 构建。

准备条件：工具链与系统要求

按 tauri-plugin-appload 的 README "Development > Requirements"，构建需要：

• Node.js 18 或更高版本
• Rust 1.77.2 或更高版本（cargo 需可用）
• pnpm

桌面应用本身的最小系统要求（来自 README "Minimum System Requirements"）：

Linux 上还要记住两点依赖限制：Tauri v2 依赖libwebkit2gtk-4.1，该库只默认存在于 Ubuntu 22.04+ 的仓库中；旧发行版还会因为 GLIBC 版本不足报错（如GLIBC_2.32 not found）。

仓库是 pnpm workspace 结构（见 pnpm-workspace.yaml）。构建涉及三个包：

• hoppscotch-selfhost-web —— 自托管 Web 前端，pnpm generate产出dist目录；
• hoppscotch-desktop —— Tauri v2 桌面壳；
• webapp-bundler —— Rust CLI 工具，把 Web 前端目录打包成bundle.zip并生成带 blake3 校验和的manifest.json（实现见 src/main.rs）。

以下命令均在仓库根目录（即 clone 下来的hoppscotch目录）下按相对路径执行。

第一步：构建自托管 Web 应用

cd packages/hoppscotch-selfhost-web pnpm install pnpm generate

generate是该包定义的 npm script，实际执行vite build（见 package.json："generate": "pnpm run build"），构建产物输出到packages/hoppscotch-selfhost-web/dist。另外该包的postinstall会运行gql-codegen生成 GraphQL 代码，安装依赖阶段就会触发。

第二步：编译 webapp-bundler

cd crates/webapp-bundler cargo build --release

注意这里的crates/webapp-bundler是相对hoppscotch-desktop包的路径，即完整路径为 packages/hoppscotch-desktop/crates/webapp-bundler，README 中的cd命令是按包内相对路径写的。构建完成后可执行文件位于该 crate 的target/release/webapp-bundler。

第三步：打包 Web 应用为 bundle

README 给出的命令：

cd target/release ./webapp-bundler --input [path-to-dist-directory] \ --output [path-to-hoppscotch-desktop]/bundle.zip \ --manifest [path-to-hoppscotch-desktop]/manifest.json

其中[path-to-dist-directory]必须指向第一步pnpm generate生成的dist目录，即packages/hoppscotch-selfhost-web/dist（README Note 明确说明）。[path-to-hoppscotch-desktop]指packages/hoppscotch-desktop目录。

与其手工替换三个占位符，也可以直接使用hoppscotch-desktop包已定义好的prepare-web脚本（package.json），它把第一到第三步串成一条命令，路径已经写死：

cd packages/hoppscotch-desktop pnpm run prepare-web

该脚本实际执行的内容：

(cd ../hoppscotch-selfhost-web && pnpm install && pnpm generate) \ && (cd crates/webapp-bundler && cargo build --release \ && cd target/release \ && ./webapp-bundler --input ../../../../../hoppscotch-selfhost-web/dist \ --output ../../../../bundle.zip \ --manifest ../../../../manifest.json)

bundler 会递归读取输入目录、按 main.rs 的逻辑压缩为 zip 并写出 manifest。运行成功时终端依次打印：

Creating bundle from directory: <dist 目录> Using bundle version: <版本号> Bundle written to: <bundle.zip 路径> Manifest written to: <manifest.json 路径> Bundle created successfully with <N> files

<N>为打包文件数量，随构建内容变化，属文档外的实际输出示例，无需固定预期。执行完成后packages/hoppscotch-desktop/下应存在bundle.zip和manifest.json两个文件，这是第三步完成的最小判据。

第四步：运行桌面应用

开发模式（README 给出的命令）：

cd packages/hoppscotch-desktop pnpm tauri dev

pnpm tauri dev会先跑vite开发服务器（tauri.conf.json 中devUrl为http://127.0.0.1:1420），然后启动 Tauri 应用，Hoppscotch Desktop 窗口应正常打开。

生产构建：README 在 "Run the development server" 一节末尾给出cd src-tauri && pnpm tauri dev作为 production build 的替代写法，但 package.json 中定义的生产脚本是build:full，等价于在hoppscotch-desktop目录下执行：

pnpm tauri build

它会先执行pnpm build（vue-tsc --noEmit && vite build）再产出可分发安装包。

可选分支——portable（便携）构建：hoppscotch-desktop包还定义了dev:portable/build:portable脚本，即追加-- --no-default-features --features portable。对应 tauri.portable.windows.conf.json 中bundle.active: false、WindowswebviewInstallMode为skip、不生成 updater 工件——即不打安装程序、不随包安装 WebView，适合需要自行放置可执行文件的分发环境。

自托管实例的连接前置配置

桌面应用要连上你的自托管实例（Community 或 Enterprise 版），该实例的.env中WHITELISTED_ORIGINS必须加入部署地址对应的应用来源。以允许连接https://hoppscotch.mydomain.com为例（README "Access Options" 中的 Note，mydomain_com为你的域名，.替换为_）：

WHITELISTED_ORIGINS=...existing_origins,app://hoppscotch_mydomain_com,http://app.hoppscotch_mydomain_com

其中app://hoppscotch_mydomain_com用于 macOS / Linux，http://app.hoppscotch_mydomain_com用于 Windows。...existing_origins表示保留该变量中已有的其他来源值，追加而非覆盖。

验证构建与连接是否成功

按以下顺序核对结果：

1. packages/hoppscotch-selfhost-web/dist目录存在（pnpm generate产物）；
2. packages/hoppscotch-desktop/下存在bundle.zip与manifest.json，且 bundler 打印了Bundle created successfully with N files；
3. pnpm tauri dev（或pnpm tauri build后的产物）能打开 Hoppscotch Desktop 窗口；
4. 连接自托管实例：打开应用，点击左上角 Hoppscotch logo，点击Add an instance，输入你的自托管实例 URL，点击Connect。

如果实例是通过 Docker 部署的，README 提示：桌面应用使用的内置服务器运行在3200端口，它属于前端容器的一部分。文档给出的运行示例（原文示例）：

docker run -p 3000:3000 -p 3200:3200 hoppscotch/hoppscotch-frontend

容器启动后，在Add an instance中输入[your-ip]:3200；若使用子路径访问方式，也可以直接填实例的基础地址。

已知限制与显示问题

• 旧发行版 Linux：产物要求 GLIBC 2.38+，老系统会看到GLIBC_2.32 not found之类的版本错误；libwebkit2gtk-4.1需 Ubuntu 22.04+ 仓库提供（见 README "Misc."）。
• Wayland 显示异常：WebKit 与显卡驱动交互可能导致 Wayland 下显示异常，README 给出的 workaround 是设置环境变量后再启动（可任选或同时使用）：

WEBKIT_DISABLE_COMPOSITING_MODE=1 hoppscotch # or WEBKIT_DISABLE_DMABUF_RENDERER=1 hoppscotch

• Ubuntu 24.04 的由来：README 说明推荐 24.04 同类发行版，是因为其自带的 WebKit2GTK 版本（2.44.0-2）在 WebKit、UI 库、Mesa 驱动与 Wayland 之间的交互上足够稳定。

完成以上步骤后，你得到的是一套可复现的自托管构建链：dist产物、bundle.zip/manifest.json包，以及指向自己实例的桌面应用。后续每次更新自托管前端，重新执行pnpm run prepare-web再跑pnpm tauri build即可刷新构建。

【免费下载链接】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