文件和文件夹

Joppa 的文件夹

系统	位置
macOS	~/Library/Application Support/joppa
Linux	~/.config/joppa

文件或文件夹	内容
config.json	项目、域名、服务和设置
processes.json	项目的进程（当它们不在 joppa.toml 中时），以及 worktree 环境的进程
team.json	每个项目在本机最后一次应用（或忽略）时的 joppa.toml：Joppa 据此指出 git pull 带来的更改
running.json	Joppa 启动且正在运行的开发服务器，以便 Joppa 未停止它们就关闭时能再次找到
control.json	本地 API 的端口和令牌，供 joppa 命令使用（只有你可以读取）
reporter.json	为 报告错误 验证过的邮箱地址及其令牌，有效期 30 天（只有你可以读取）
telemetry.json	你的 隐私 选择和统计用的随机 ID
crashes/	尚未发送的崩溃报告（仅在打开 发送崩溃报告 时）
logs/	Joppa 日志：joppa.log，超过 5 MB 后为 joppa.1.log（只有你可以读取）
ca/	证书颁发机构：rootCA.pem 及其密钥 rootCA-key.pem（只读）
snapshots/<卷>/<数据库>/	数据库的快照（Joppa Pro）：每个快照一个 .dump（PostgreSQL）或 .sql.gz（MySQL、MariaDB）以及一个 .json，超过 每个数据库保留 的数量后删除最旧的
analytics/	按域名统计的数据，每分钟一行，保留 7 天
php/<version>/	已下载的 PHP 构建
php/xdebug/<8.x>/	某个 PHP 版本的 Xdebug：xdebug.so、加载它的 xdebug.ini 以及 joppa.json（版本、校验和）
bin/	遵循 .php-version 的 php 和 composer 命令
share/cloudflared	cloudflared，如果它是通过 下载 cloudflared 为公开链接下载的（已校验 SHA-256 指纹）
share/known_hosts	localhost.run 和 Pinggy 的主机密钥，用于它们的 ssh 隧道

许可证不在这个文件夹中：它保存在系统钥匙串中（服务 com.getjoppa.license），已保存的 ngrok 令牌也在那里（服务 com.getjoppa.ngrok）。

在你的项目中

Joppa 只会在项目中写入你确认过的内容：

文件	何时写入
.env	关联服务、HTTPS 地址、编辑（始终附带 diff）
.env.joppa-backup	首次写入时（包括迁移），原始 .env 的副本
joppa.toml	如果你与团队共享项目配置（参见 joppa.toml）
.node-version、package.json	如果你固定了 Node 或包管理器
.php-version	如果你固定了 PHP
.php.ini	如果你编写了 项目的 php.ini
vite.config.*、astro.config.*	如果你点击了 修复文件

在 Joppa 准备的 worktree 中：它缺少的 .env、.env.local、.env.development(.local)、.dev.vars 和 .php.ini 文件，从项目复制而来并换成 worktree 的地址。新建 worktree 会在仓库旁边的 <项目>-worktrees/ 中创建它的文件夹。

这些文件夹之外

• Shell 配置文件（~/.zshrc…）：只有 # >>> Joppa (PHP) >>> 和 # >>> Joppa (Node) >>> 代码块，并且仅在你启用时写入。
• Vite+：首次启动时安装到它的默认文件夹（~/.local/share/vite-plus 和 ~/.config/vite-plus；若之前已在 ~/.vite-plus 则沿用），并附带 Node LTS 和 bun。Joppa 每天更新它。
• .test 解析：一个把 *.test 交给 Joppa DNS 服务器（127.0.0.1:15353）的文件，用你的密码写入：macOS 上是 /etc/resolver/test，Linux 上是 /etc/systemd/resolved.conf.d/joppa.conf 或 /etc/NetworkManager/dnsmasq.d/joppa.conf。它以一行 # Joppa 开头。参见 解析 .test 域名。
• joppa 命令：/usr/local/bin 或 ~/.local/bin 中的一个链接，仅在你安装时创建。
• AI 助手：其配置中的 mcpServers.joppa 项，仅在你接入时写入。
• 容器：你的运行时中的 joppa-<engine> 及其卷 joppa-<engine>-<version>。

完全移除

设置 › 卸载 › 卸载 Joppa… 会列出 Joppa 在这台电脑上安装的内容；勾选要移除的项：

项目	移除的内容
AI 助手的 MCP 服务器	Claude Code、Claude Desktop 和 Cursor 配置中的 mcpServers.joppa 项
joppa 命令	/usr/local/bin 或 ~/.local/bin 中的 joppa 链接
shell 配置中的 PHP 和 Node	~/.zshrc、~/.bash_profile、~/.bashrc 和 joppa.fish 中的 # >>> Joppa (PHP) >>> 和 # >>> Joppa (Node) >>> 代码块
服务的容器	joppa-<engine> 容器，以及 Joppa 为扩展构建的镜像
服务的数据	joppa-<engine>-<version> 卷：数据库、邮件、索引（默认不勾选）
CA 信任	从你的登录钥匙串中移除 “Joppa local CA”（需要你的密码）；如果是终端命令把它放进了系统钥匙串，则从系统钥匙串中移除（需要管理员密码）
.test 解析	Joppa 的解析文件（/etc/resolver/test…），需要你的密码。其他工具（Herd、Valet、dnsmasq）的文件会保留
许可证	释放这台 Mac 的席位，并从钥匙串中移除密钥
Joppa 文件夹	上面的文件夹，以及窗口数据（~/Library/WebKit/dev.joppa.app、缓存…）
应用	Joppa.app（macOS）或 .AppImage 文件（Linux）

Joppa 文件夹和应用会在 Joppa 退出后删除：此时按钮显示为 卸载并退出。项目中的文件（.env、.env.joppa-backup、joppa.toml…）永远不会被改动。

在终端中，joppa uninstall 的作用相同：参见joppa 命令 › 卸载。

失败的步骤（取消了密码、运行时已停止、没有网络无法释放许可证）会单独报告，不会阻止其他步骤。手动完成的方法：docker rm -f joppa-postgres、docker volume rm joppa-postgres-17，在 macOS 上打开钥匙串访问 › 登录（或系统） › “Joppa local CA”。