安装

下载

在 下载页面 获取最新版本：

系统	文件
macOS（Apple 芯片和 Intel）	.dmg：把 Joppa 拖到“应用程序”中
Linux x86_64	.AppImage（便携版，需先设为可执行：chmod +x Joppa_amd64.AppImage）或 .deb（Debian、Ubuntu：sudo apt install ./Joppa_amd64.deb）

在 macOS 上首次打开

Joppa 暂未经过 Apple 签名，因此 macOS 会阻止首次打开。这很正常，而且只需操作一次。

1. 从“应用程序”打开 Joppa。macOS 提示未打开“Joppa”：点击 完成，不要点 移到废纸篓。
2. 打开 系统设置 › 隐私与安全性，向下滚动到 安全性。
3. 在“已阻止 Joppa 以保护你的 Mac”旁，点击 仍要打开。
4. 再次点击 仍要打开 确认，然后输入密码或使用触控 ID。

下载页面 用图示展示了这些步骤。

首次启动时，Joppa 会创建配置文件夹和证书颁发机构，并启动 HTTPS 代理。之后它常驻在菜单栏中：关闭窗口并不会让它停止。

信任证书

Joppa 使用本地证书颁发机构（CA）为每个域名签发证书。要让浏览器显示锁形图标，你的系统必须信任这个颁发机构。这只需做一次，需要管理员密码。

打开 设置 › 证书颁发机构：Joppa 会显示适用于你这台机器的确切命令，并附有复制按钮。

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  "$HOME/Library/Application Support/joppa/ca/rootCA.pem"

Joppa 会自动检查信任状态：完成后，状态栏会变为 CA joppa 正常。

Linux

sudo cp ~/.config/joppa/ca/rootCA.pem /usr/local/share/ca-certificates/joppa-rootCA.crt
sudo update-ca-certificates

80 和 443 端口

代理监听 127.0.0.1 的 443 端口（HTTPS）和 80 端口（重定向到 HTTPS）。它只接受来自本机的连接。

• macOS：无需任何操作。
• Linux：1024 以下的端口需要特殊权限。如果 Joppa 无法打开这些端口，它会显示要运行的命令：

sudo setcap cap_net_bind_service=+ep /path/to/joppa

如果只有 80 端口不可用，代理仍会运行；只是 HTTP → HTTPS 重定向会被停用。

解析 .test 域名

浏览器需要知道 myproject.test 指向你的机器（127.0.0.1）。Joppa 不会修改你的 DNS 配置：如果代理在运行而域名没有响应，请让 *.test 解析到 127.0.0.1。

在 macOS 上使用 dnsmasq（Homebrew）：

brew install dnsmasq
echo 'address=/.test/127.0.0.1' >> "$(brew --prefix)/etc/dnsmasq.conf"
sudo brew services start dnsmasq
sudo mkdir -p /etc/resolver
echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/test

容器运行时（可选）

域名和 HTTPS 不需要其他任何东西。如需使用 服务（PostgreSQL、Redis、Mailpit…），请安装以下运行时之一：OrbStack、Docker Desktop、Colima 或 Podman。参见 容器运行时。

检查

窗口底部的状态栏汇总了一切：

joppa   代理 :443   CA joppa 正常   2/2 个域名在线   1/1 个服务

接下来可以阅读 快速上手。