故障排除
最常见的问题，如域名无法解析、证书被拒绝、443 端口被占用、缺少 Docker，以及解决方法。
请始终先查看窗口底部的状态栏（或运行 joppa status）：它会告诉你代理是否在运行、CA 是否受信任，以及有多少个域名在响应。
域名无响应
joppa diagnose <域名>（或 MCP 工具 diagnose）会一次性检查下面的所有内容，并告诉你需要修复什么：代理、名称解析、证书、开发服务器的端口，以及应占用该端口的进程的状态。
浏览器找不到网站（DNS_PROBE_FINISHED_NXDOMAIN）。.test 名称没有解析到你的机器：状态栏显示 .test 无法解析。点击它，或点击横幅中的 配置 / 修复：Joppa 会写入它的解析文件（需要你的密码）并清空 DNS 缓存。设置 › .test 解析 › 测试域名 会准确告诉你问题出在哪里：
| 信息 | 解决方法 |
|---|---|
| 「尚无系统文件把 .test 交给 Joppa」 | 配置 |
| 「系统尚未解析 …」 | 修复：重写该文件并清空缓存 |
| 「… 解析到 10.…，而不是本机」 | VPN 或网络的 DNS 在响应 .test：修复 会重写 Joppa 的文件并清空缓存；如果 VPN 强制使用自己的 DNS，请把该域名添加到 /etc/hosts |
| 「Joppa 的 DNS 服务器未运行」 | 15353 端口被其他程序占用：释放它，然后重新启动 Joppa |
| 「… 已到达 Joppa，但没有项目路由它」 | 把该域名添加到某个项目 |
参见 安装 › 解析 .test 域名。
「开发服务器无响应」（502）。 代理在工作，但目标端口上没有任何程序在监听。启动开发服务器，在“域名”标签页中检查它的端口，或者让 Joppa 通过 进程 启动它。
「域名未配置」。 这个名称没有关联到任何项目，或者该域名已被停用。请在“域名”标签页中添加它。
完全没有响应。 代理已停止（窗口顶部有横幅）：点击 启动代理。
“Blocked request. This host is not allowed.”
Vite 或 Astro 拒绝了该域名。域名 标签页会提供 修复文件。参见 框架设置。
浏览器显示“不安全”
系统不信任该 CA：状态栏显示 CA … 未受信任。点击窗口顶部横幅中的 批准（或 设置 › 证书颁发机构 中的 批准颁发机构），然后重启浏览器。在 Linux 上，还要把 CA 导入 Firefox。参见 证书。
生成的 URL 是 http://
你的框架不知道自己位于 HTTPS 代理之后。Laravel：参见 Laravel 与反向代理。其他框架会读取 X-Forwarded-Proto。
代理无法启动
- 其他服务器占用了 443 端口（Lerd、Laravel Herd、Valet、Apache、Caddy、MAMP、DDEV、某个容器…）：横幅会指出它的名字（「端口 443 被 … 占用」）并提议停止它，然后启动代理。参见 80 和 443 端口被占用。
- 横幅无法识别占用者（「其他用户的进程」）：运行横幅显示的命令（
sudo lsof -nP -iTCP:443 -sTCP:LISTEN），停止该程序，然后点击 启动代理。 - Linux，权限被拒绝：
sudo setcap cap_net_bind_service=+ep <joppa 的路径>。 - 「HTTP → HTTPS 重定向已停用」：只有 80 端口被占用；HTTPS 仍然可用。
服务无法启动
- 「没有容器运行时」：安装或启动 OrbStack、Docker Desktop、Colima 或 Podman。参见 容器运行时。
- 「端口 5432 被 … 占用」：另一个 PostgreSQL 正在运行（Homebrew、Postgres.app、Docker）。释放端口 或 更换端口。参见 端口被占用。
- 首次使用扩展时：构建 PostgreSQL 镜像需要几分钟。
进程反复崩溃
打开终端（⌘ J）并切换到该进程的标签页：最后的错误就在那里。达到你设置的重新启动次数后，Joppa 会放弃并提示你。参见 崩溃后重新启动。
项目读不到新变量
开发服务器只在启动时读取 .env：请重启它们（如果由 Joppa 启动，可在“进程”标签页中操作）。
Vite+ 无法安装
Joppa 会在首次启动时安装 Vite+；离线时安装会失败，JavaScript 模板保持灰色不可用。联网后，在 新建项目 窗口或 设置 › Node 中点击 重试。安装会从 https://vite.plus 下载官方脚本，再从各自官网下载 Node LTS 和 bun。参见 Node、bun 和 PHP 版本。
手机打不开共享的网站
对于局域网共享：
- 同一网络。 手机必须与 Mac 连接同一个 Wi-Fi，而不是使用 4G/5G。“访客” Wi-Fi 或公共 Wi-Fi 往往会把设备彼此隔离：请换一个网络，或使用公开链接。
- macOS 防火墙。 如果你拒绝了传入连接的请求：前往 系统设置 › 网络 › 防火墙 › 选项，允许 Joppa。如果勾选了“阻止所有传入连接”，任何连接都无法通过。
- VPN。 Mac 上启用的 VPN 可能导致显示的是它的地址而不是 Wi-Fi 的地址。关闭 VPN，然后关闭并重新打开共享。
- 页面能显示，但脚本或 API 加载不了：它们来自另一个
.test域名，手机并不认识它。请同时共享那个域名，或参见应用看到的内容。 - 登录无法保持（你被送回登录页）：
__Secure-或__Host-Cookie 要求 HTTPS；请使用公开链接。
公开链接打不开
- “隧道已关闭”：窗口会显示客户端的最后几条消息。最常见的原因是网络阻止了出站连接（企业代理、防火墙），或服务暂时不可用；点击 重试，或选择另一个隧道。
- 当存在
~/.cloudflared/config.yml（或config.yaml）文件（命名隧道的配置）时，cloudflared 会拒绝创建快速隧道：共享期间请先将其重命名。 - ngrok：没有令牌（在 Joppa 中或通过
ngrok config add-authtoken）时，ngrok 拒绝启动。 - Pinggy 会在 60 分钟后关闭免费隧道：重新打开即可（地址会改变）。
- 下载 cloudflared 时提示“校验和无效”：收到的压缩包不是 Cloudflare 发布的那个（代理修改了下载内容、文件损坏）。Joppa 已将其删除；请换一个网络重试，或自行安装 cloudflared（
brew install cloudflared）。
joppa 命令提示 Joppa 未运行
退出码为 3。启动应用，或加上 --launch。如果应用正在运行，请在 设置 › 命令行 中重新安装该命令。
报告错误
侧边栏底部的 报告错误（或 ⌘ K 命令面板中的同名命令）可以向团队发送报告，无需账户：
- 如果这台 Mac 上已激活许可证，表单会直接打开：我们会回复到许可证的邮箱。
- 否则，输入你的邮箱地址并点击 获取验证码：6 位验证码会通过邮件发送给你。输入后点击 验证。这台 Mac 会记住该地址 30 天；更换地址 会将其清除。
- 填写 出了什么问题，再填写 详情（你当时在做什么、发生了什么、你期望的结果），然后点击 发送报告（⌘ ↵）。
报告会附上 Joppa 版本和你的系统信息。你会收到一份带编号（JP-…）的副本；我们会回复到你的邮箱。
附上最近的日志 默认开启，会附上 Joppa 日志的最后几行（最多 150 KB），你的个人文件夹显示为 ~。查看将发送的内容 会在发送前显示它们。日志作为报告的附件发送给团队，不会保存在网站上。
上方的 文档 会以应用的语言打开本文档。
仍然无法解决？
直接在应用中联系我们：侧边栏底部的 支持（或在 ⌘ K 命令面板中选择「联系支持」）。消息会附上 Joppa 版本和你的系统信息。未激活许可证时，应用会带你前往 getjoppa.com：无论是否有许可证，你都会通过邮件收到登录链接，随后表单会自动打开。网站页脚也提供同样的表单。
你也可以写信至 [email protected]，并附上 joppa status 的输出。只是简单的问题：[email protected]。