进程
让 Joppa 按正确的顺序启动你的开发服务器和 Compose 容器，内置终端，支持在打开 Joppa 时启动，并在崩溃后重新启动。
进程 标签页（P）从 Joppa 运行项目：它的开发服务器（package.json 中的 dev 脚本、Nx 目标、PHP 服务器）和基础设施（Docker Compose 服务）。每个进程都有自己的状态、端口和日志。
分析项目
第一次使用时，点击项目页面顶部（打开 旁边）或标签页中的 分析项目。在完成分析之前，Joppa 不会启动任何内容：域名会一直离线，直到你启动服务器。Joppa 会读取 package.json、workspaces 和 Docker Compose 文件，然后显示 Joppa 对项目的理解。在你确认之前不会启动任何内容。
| 列 | 内容 |
|---|---|
| 在「全部启动」中 | 取消勾选某个进程，它就不会和其他进程一起启动；但仍可单独启动 |
| 进程 | 进程名：web、api、postgres |
| 命令 | bun run dev，或 Compose 服务 |
| 端口 | 可修改 |
| 端口来源 | 脚本、配置、代码、.env、compose 或 默认 |
| 就绪条件 | 对于有端口的开发服务器：Joppa 用来判断其已就绪的 HTTP 路径（默认 /），或 tcp |
「等待 …」这一行表示依赖关系：开发服务器会等待它所依赖的 Compose 容器就绪。
开发服务器命令下方的 + 操作 可为其添加操作。
如何确定端口
按以下顺序：
- 脚本中带默认值的变量（
${PORT:-3000}）：Joppa 会为其赋值； - 脚本中的
--port、-p或PORT=； - 框架配置中的
port:（vite.config、astro.config），包括写在一行中的形式（server: { port: 5400 }），或 Nx 目标的options.port； .env中的PORT；- 框架的默认端口：Vite 和 VitePress 5173、Astro 4321、Next.js、Nuxt、Create React App 和 Docusaurus 3000、Angular 4200、Wrangler 8787、Vue CLI 8080、Gatsby 8000、Storybook 6006、Expo 8081。
对于其他 Node 服务器，Joppa 会在代码中查找端口（.listen(3000)、process.env.PORT ?? 3000）。
包管理器取自 lockfile，其次是 packageManager 字段，否则使用 npm。
每个包的脚本
Joppa 使用包的 dev 脚本；如果没有，则使用 develop、serve，或启动开发服务器的 start（react-scripts start、ng serve、expo start…）。生产环境的 start（node dist/server.js）会被忽略。
PHP 服务器
| 项目 | 线索 | 命令 |
|---|---|---|
| Laravel | artisan 文件 |
php artisan serve --host=127.0.0.1 --port=${SERVER_PORT:-8000} |
| Symfony、其他 PHP | public/index.php 和 composer.json |
php -S 127.0.0.1:${PORT:-8000} -t public |
端口取自 .env 中的 SERVER_PORT（Laravel）或 PORT，否则为 8000。使用的 php 是 固定的版本。
Laravel worker
除了 php artisan serve，Joppa 还会提供应用所用的后台进程，这些信息读取自 composer.json、.env 和代码：
| 进程 | 何时 | 命令 | 勾选 |
|---|---|---|---|
queue |
QUEUE_CONNECTION 不是 sync（Laravel 11 及以上：默认为 database） |
php artisan queue:work，或 composer run dev 中的命令（入门套件中为 queue:listen --tries=1，每个 job 都会重新读取代码） |
是；为 sync 时提供但不勾选 |
horizon |
已安装 laravel/horizon |
php artisan horizon，当队列经由 Redis 时取代 queue |
如果 QUEUE_CONNECTION=redis |
scheduler |
始终 | php artisan schedule:work |
如果应用安排了任务（routes/console.php 中的 Schedule::，Kernel 中的 $schedule->） |
reverb |
已安装 laravel/reverb |
php artisan reverb:start --host=127.0.0.1 --port=${REVERB_SERVER_PORT:-8080} |
如果 BROADCAST_CONNECTION=reverb |
pail |
已安装 laravel/pail |
php artisan pail --timeout=0 |
否：Joppa 已经显示日志 |
这些都是没有端口的进程，Reverb 除外：它的端口取自 .env 中的 REVERB_SERVER_PORT，否则为 8080，Joppa 会设置这个变量，以便 worktree 改变它。未勾选的进程仍留在列表中，可以手动启动。
Monorepo
Joppa 会在仓库声明包的地方找到它们：
| 文件 | 形式 |
|---|---|
package.json |
workspaces（npm、yarn、bun），列表形式或 { "packages": [...] } |
pnpm-workspace.yaml |
packages: |
lerna.json |
packages（默认为 packages/*） |
nx.json |
仓库中的每个 project.json、其 serve / dev 目标，以及 Nx 插件推断出的目标（@nx/vite/plugin、@nx/next/plugin） |
支持 apps/*、packages/**（任意深度）等模式以及 !packages/legacy 这样的排除规则；node_modules、dist 和隐藏文件夹会被忽略。Nx 目标通过 nx run <项目>:<目标> 启动。
根目录的 dev 脚本决定在每个包中运行哪个任务，以及在哪些包中运行：
| 根脚本 | 任务 | 包 |
|---|---|---|
turbo dev、turbo run dev、turbo watch dev |
dev |
所有包含该任务的包 |
turbo run start:dev --filter=web... |
start:dev |
web |
nx run-many -t serve -p shop admin |
serve |
shop、admin |
nx serve shop、nx run shop:serve |
serve |
shop |
pnpm -r --parallel dev、pnpm --filter ./apps/* dev |
dev |
全部 / apps/ 中的包 |
bun run --filter '@acme/*' dev |
dev |
@acme scope 中的包 |
npm run dev -w apps/web -w apps/api |
dev |
web、api |
过滤器可以通过包名、文件夹或模式（apps/*、@acme/*）指定包；支持 Turborepo 的 ...、^、{…} 和 !docs 排除规则。不在根 dev 中的包保持未勾选，除非有域名指向它。
当根目录的 dev 脚本一次启动多个应用时，Joppa 会提供两个选项：
- 分别启动 · 每个应用独立的状态和日志（推荐）；
- 保持原样：在同一个终端中运行根命令。
保存：仅限本机或供团队共享
- 保存 会把配置保存在 Joppa 中，仅限本机。
- 勾选 在仓库中写入 joppa.toml，供团队共享 即可共享：配置会写入项目根目录的
joppa.toml文件，供你提交。该文件存在时，以它为准。参见 joppa.toml 参考。如需同时共享域名、服务、数据库和版本，请使用进程列表下方的 在 joppa.toml 中共享配置 链接。
保存并启动 会立即启动所有进程。
启动和停止
- 项目页面顶部的 ▶ 全部启动 / ■ 全部停止，或使用 ⌘ K 命令面板（「全部启动：myproject」）。只要有一个进程在运行，按钮就会变为 ■ 全部停止。
- 每个进程都可以在标签页中或通过命令面板单独启动、停止或重启。
进程分为 应用（「dev」脚本）和 基础设施（Docker Compose，以 docker compose up -d --wait 启动：Joppa 会等待健康检查）两组。标题栏显示启动顺序以及正在运行的数量。每组都有自己的 ▶ 全部启动 / ■ 全部停止 按钮，只作用于本组的进程：例如只启动基础设施而不启动应用。与项目的按钮一样，它会跳过未勾选「全部启动」的进程。
| 状态 | 含义 |
|---|---|
| 已停止 | — |
| 正在停止 | 已请求停止，进程尚未退出 |
| 等待中 | 正在等待它所依赖的进程 |
| 启动中 | 已启动，但尚未响应（参见进程何时就绪） |
| 运行中 | 已启动（无端口的进程） |
| 在线 | 它在端口上响应 HTTP 请求 |
| 失败 | 因错误而停止 |
| 在 Joppa 之外启动 | 该端口已由一个非 Joppa 启动的进程提供服务 |
| 无 Docker | Compose 服务，但没有正在运行的运行时 |
| 休眠 | 因没有请求被 Joppa 停止：下一个请求会唤醒它（参见空闲休眠） |
侧边栏中项目旁以及「项目」页面中项目卡片上的 ▶ 6/7 计数器显示「全部启动」中有多少个进程正在运行；窗口底部的状态栏汇总所有项目（6/7 个进程）。▶ 的颜色：全部运行时为绿色，有进程已停止、正在启动或在 Joppa 之外启动时为橙色，只有在某个进程失败时才为红色。将鼠标悬停在计数器上可查看详情。 当项目的开发服务器处于休眠状态时，▶ 会变为蓝色的 z。
如果端口被其他程序占用，Joppa 会提示你，并提供 释放端口。
停止时会先发送 SIGTERM，6 秒后再发送 SIGKILL，发给该脚本启动的所有进程。启动它的脚本结束后仍在运行的开发服务器依然由 Joppa 跟踪：保留其日志、状态和停止按钮。
在终端中：joppa procs、joppa start|stop|restart <项目> [进程] 和 joppa logs <项目> [进程]（参见 joppa 命令）。Claude Code 或 Cursor 等助手可以通过 MCP 服务器 的 list_processes、start_process、restart_process、process_logs 和 run_process_action 工具做同样的事。
打开 Joppa 时启动
开关 打开 Joppa 时启动 会在每次启动 Joppa 时对该项目执行一次「全部启动」。这是本机的偏好设置：永远不会写入 joppa.toml。
如果通过 git pull 收到的 joppa.toml 中的命令有改动，Joppa 不会自行运行它们：系统通知会提示该项目未启动。请检查这些命令，然后点击 全部启动：之后打开 Joppa 时启动将照常进行。
崩溃后重新启动
设置 崩溃后重新启动 决定 Joppa 对崩溃的开发服务器重新启动多少次：从不、1、2、3（默认）、5 或 10 次。
- 两次重新启动之间的等待时间逐次翻倍：1 秒、2 秒、4 秒、8 秒……最长 30 秒。
- 稳定运行 60 秒后，计数器归零。
- 超过次数后，Joppa 会放弃并显示：「重新启动 3 次后再次崩溃：Joppa 已放弃。」
- 你主动停止进程会取消待执行的重新启动。
此设置仅适用于开发服务器（不适用于 Compose 容器），并且只保存在本机。
修复失败的进程
当某个进程彻底停止（Joppa 在多次重新启动后放弃，或已关闭重新启动）时，无论打开的是哪个标签页，项目页面顶部都会出现红色横幅：显示该进程、停止原因以及它最后输出的几行。
- 修复 会重新启动它以及它所依赖的进程，不影响其他进程。
- 打开终端 显示它的完整日志。
- 忽略 会隐藏横幅，直到下一次失败。
进程何时就绪
有端口的开发服务器在响应 HTTP 请求时才算 在线，而不仅仅是端口接受连接：Joppa 在其端口上请求 GET /，任何响应都算数，即使是 404 或 500。终端会记录这一时刻：「1.2 秒后就绪（GET / → 200）」。等待它的进程（「等待 …」、dependsOn）在此之后才会启动。
分析中的 就绪条件 列（joppa.toml 的 probe 字段）可以改变 Joppa 请求的内容：
| 值 | 何时就绪 |
|---|---|
| （空） | GET / 得到响应 |
/health、/up… |
该路径得到响应 |
tcp |
端口接受连接 |
如果端口接受连接但 30 秒内没有任何 HTTP 响应，或者它以其他协议响应，Joppa 仍会将其视为已就绪。一旦就绪，Joppa 不再发出请求，只检查端口是否仍在响应。Docker Compose 服务在其健康检查通过时就绪；没有健康检查时，在其端口响应时就绪。
空闲休眠
打开许多 worktree、每个都运行自己的开发服务器时，内存很快就会耗尽。Joppa 会让无人使用的项目的开发服务器进入休眠：在其域名 15 分钟 内没有请求后，Joppa 会停止它们并标记为 休眠。
下一个访问其域名的请求会唤醒它们：
- 代理暂存该请求；
- Joppa 重新启动处于休眠的开发服务器以及它们所依赖的进程；
- 一旦该域名的服务器就绪，请求就会被转发给它。
需要等待超过 3 秒的页面会显示「正在唤醒 web…」，它每秒自动重新加载，直到服务器响应。其他请求（fetch、静态资源、HMR 的 WebSocket）最多等待 90 秒。唤醒后，Vite 的 HMR 会自动重新连接。
进程 标签页中的 无请求 … 后休眠 开关可按项目设置延迟（5 分钟到 2 小时）或关闭休眠。worktree 环境 默认开启，其他项目默认关闭。这是你本机的偏好设置，永远不会写入 joppa.toml。
- 只有开发服务器会休眠：Docker Compose 容器和 Joppa 服务会继续运行。
- 当项目的某个进程正在启动、重新启动或执行操作时，Joppa 不会让该项目休眠；没有任何域名指向开发服务器的项目（没有请求能唤醒它）以及代理停止时也不会。
- 一直打开但没有活动的标签页不会阻止休眠：当你回到该标签页时，HMR 客户端会重新连接并唤醒服务器。
- ▶ 也会唤醒休眠的进程；■ 全部停止 会让它退出休眠：请求不再会启动它。
休眠 状态显示在标签页、域名的状态列、终端以及项目计数器上（蓝色的 z，状态栏中显示「4 个休眠」）。MCP 工具 list_processes 将其返回为 asleep。
操作
操作是附加在进程上的一次性命令：migrate → php artisan migrate、seed → php artisan db:seed、test → bun test。在 进程 标签页中进程名称旁边，或在打开该进程的终端栏中，一键即可运行。其输出写入该进程的终端，位于「▶ migrate $ php artisan migrate」和「migrate：已完成」（或「migrate：失败（代码 1）」）之间。
- 它在进程的文件夹中运行，使用该进程的环境变量，无论进程是否在运行。
- 运行期间再次点击会停止它。
- 同一个操作同时只能运行一次。
操作在分析中声明（重新查看分析）：在开发服务器命令下方点击 + 操作，然后填写名称和命令。Joppa 会为 Laravel 建议 migrate、seed 和 test，为 JavaScript 项目建议 test 和 lint。项目有 joppa.toml 时，它们会写入其中。助手可以通过 MCP 服务器 的 run_process_action 工具运行它们。
内置终端
⌘ J 可在任意界面打开窗口底部的终端。收起时，它为每个进程显示一个状态方块；展开时，先是 全部 标签页，然后每个进程一个标签页。
- ⌕ 筛选：只显示包含某段文本的行。
- ● 跟随：始终停在最新的行。
- 清空、放大 / 缩小。
- 调整大小：拖动顶部边缘（或用键盘 ↑ / ↓）；双击恢复默认高度。Joppa 会记住上次的高度。
Joppa 为每个进程保留最近 5,000 行。出错时，终端会提供合适的操作：释放端口 或 重新启动。