故障排除

请始终先查看窗口底部的状态栏（或运行 joppa status）：它会告诉你代理是否在运行、CA 是否受信任，以及有多少个域名在响应。

域名无响应

浏览器找不到网站（DNS_PROBE_FINISHED_NXDOMAIN）。.test 名称没有解析到你的机器。参见 安装 › 解析 .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。

代理无法启动

• Lerd 占用了端口：横幅会提供 停止 Lerd 并启动。参见 与 Lerd 共存。
• 其他程序占用了 443 端口（Valet、nginx、Caddy、其他代理）：请停止它。
• 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 启动，可在“进程”标签页中操作）。

joppa 命令提示 Joppa 未运行

退出码为 3。启动应用，或加上 --launch。如果应用正在运行，请在 设置 › 命令行 中重新安装该命令。

仍然无法解决？

直接在应用中联系我们：侧边栏底部的 支持（或在 ⌘ K 命令面板中选择「联系支持」）。消息会附上 Joppa 版本和你的系统信息。未激活许可证时，应用会带你前往 getjoppa.com：无论是否有许可证，你都会通过邮件收到登录链接，随后表单会自动打开。网站页脚也提供同样的表单。

你也可以写信至 [email protected]，并附上 joppa status 的输出。只是简单的问题：[email protected]。