添加项目
Joppa 如何分析文件夹、为项目命名、找到其开发服务器并为它们推荐域名。
三种添加方式
- 拖放：把文件夹拖到窗口中的任意位置（「松开以添加项目」）。
- 按钮或快捷键：侧边栏中 项目 旁边的 + 新建、首页上的 添加项目，或在任意位置按 N。
- 终端：在 TUI 的“项目”部分按 a，或使用 MCP 工具
add_project。
添加项目 窗口会显示 Joppa 找到的内容；在你确认（⌘ ⏎）之前，不会保存任何内容。
名称和图标
名称取自 package.json 的 name 字段（去掉 @org/ scope），否则取文件夹名。它会被转换为不含重音和空格的小写形式：Kiné Santé 变为 kine-sante。
图标根据名称生成。你可以随时在项目页面按 I 更换它：生成的图案、首字母、图形，或你自己的图片（.svg、.png、.jpg、.webp，最大 180 KB），会以 Joppa 的配色进行抖动处理。
Joppa 能检测到什么
| 技术栈 | 线索 | 默认端口 |
|---|---|---|
Vite、Vite+（vp）、React Router、Remix、SvelteKit |
dev 脚本 |
5173，或 vite.config 中的 port: |
| Astro | dev 脚本 |
4321，或 astro.config 中的 port: |
| Next.js | dev 脚本 |
3000 |
| Nuxt | dev 脚本 |
3000 |
| Angular、Nx（Angular、webpack） | ng serve、Nx 目标 |
4200 |
| Create React App、Docusaurus | react-scripts start、docusaurus start |
3000 |
| Vue CLI、Gatsby、Storybook、Expo | 各自的命令 | 8080、8000、6006、8081 |
| Node（其他服务器） | 脚本或代码中写明的端口 | 找到的端口 |
| Laravel | artisan 文件 |
8000（php artisan serve） |
| Symfony、其他 PHP | public/index.php 和 composer.json |
8000（php -S） |
| Bun | bun.lock / bun.lockb |
— |
| Docker Compose | compose.yaml、docker-compose.yml… |
已发布的端口 |
Joppa 会读取根目录以及 monorepo 中每个包 的 dev 脚本：npm、yarn 或 bun 的 workspaces、pnpm-workspace.yaml、lerna.json、Nx 项目。端口可以写成以下形式：--port 3000、-p 3000、--port=3000、PORT=3000、${PORT:-3000}。详情见 进程。
对于 Laravel，基础域名指向 php artisan serve；只提供静态资源的 Vite 服务器不会获得域名。
推荐的子域名
如果只有一个服务器，项目会获得基础域名：myproject.test。在 monorepo 中，每个应用会根据其文件夹名获得一个子域名：
| 应用文件夹 | 域名 |
|---|---|
web、app、frontend、client、dashboard |
app.myproject.test |
marketing、site、www、website、landing、home |
myproject.test |
api、server、backend |
api.myproject.test |
其他（docs、admin…） |
docs.myproject.test |
如果两个应用会得到相同的名称，则会编号：app、app2。
Docker Compose 的 Web 界面
发布了已知 Web 界面的 Compose 服务也会获得自己的域名：
| 服务 | 端口 | 域名 |
|---|---|---|
| Mailpit、MailHog | 8025 | mail.myproject.test |
| MinIO（控制台） | 9001 | minio.myproject.test |
| RabbitMQ（管理界面） | 15672 | rabbitmq.myproject.test |
| Adminer | 8080 | adminer.myproject.test |
| phpMyAdmin | 80 | phpmyadmin.myproject.test |
| pgAdmin | 80 | pgadmin.myproject.test |
其他已发布的端口（数据库、缓存）会列为「未路由（非 Web 界面）」。如果 Compose 中包含 PostgreSQL、MySQL、MariaDB、Redis 或 Valkey，窗口还会提议将它们的数据导入 Joppa：参见 从 Docker Compose 导入。
带有 joppa.toml 的仓库
当文件夹中包含 joppa.toml（团队共享的配置）时，窗口会以它为准：
- 名称 取自其
[project]部分； - 域名 即其中的
[[domain]]，显示的来源为「joppa.toml」； - 在 团队配置 · joppa.toml 下，计划逐行列出其余步骤：创建服务器或复用本机已有的服务器、创建数据库及其扩展、关联项目、写入
.env（查看差异）、固定 Node、包管理器和 PHP 的版本、设置 worktree。已经就绪的步骤会折叠在「已就绪」下。
取消勾选你不需要的内容：依赖它的步骤也会随之取消勾选。在此处无法完成的步骤会显示为灰色并注明原因：仅限 Joppa Pro 的引擎、已被其他项目占用的域名。差异会被提示，但不会阻止任何操作：本机上版本与要求不同的 PostgreSQL 服务器会被复用，仓库中的 .node-version 优先于 [runtime] 部分。
添加并准备（⌘ ⏎）会添加项目，然后执行勾选的步骤。不会删除或覆盖任何内容，也不会启动任何进程：它们会在 进程 标签页中等待。
之后，当 git pull 修改了该文件时，项目页面会提示并提议应用更改：参见 应用文件。
没有检测到服务器？
手动添加域名：一个子域名（admin）或完整域名，加上一个端口。之后你随时可以在 域名 标签页中添加更多。
项目页面
添加后，项目会有自己的页面和以下标签页：
| 标签页 | 快捷键 | 内容 |
|---|---|---|
| 域名 | D | 域名、目标和状态 |
| 进程 | P | 由 Joppa 启动的开发服务器和容器 |
| 环境 | E | 已关联的服务和 .env 编辑器 |
| 运行时 | R | Node、包管理器和 PHP 的版本 |
| Worktree | W | 每个 git worktree 一个环境 |
| 分析 | S | 流量、延迟、错误和可用性 |
| 检查器 | Q | 最近的请求、其请求头和正文，以及重放 |
操作 菜单（⋯）提供 重命名…（可选「同时重命名域名」）、更换图标…、在 joppa.toml 中共享配置（参见 joppa.toml）、在访达中显示 和 从 Joppa 移除。移除项目会停止它的开发服务器并忘记其本地配置；它的文件夹以及可能存在的 joppa.toml 不会被改动。