添加项目

三种添加方式

• 拖放：把文件夹拖到窗口中的任意位置（「› 松开以添加该文件夹」）。
• 按钮或快捷键：侧边栏中 项目 旁边的 + 新建、首页上的 添加项目，或在任意位置按 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	dev 脚本	5173，或 vite.config 中的 port:
Astro	dev 脚本	4321，或 astro.config 中的 port:
Next.js	dev 脚本	3000
Nuxt	dev 脚本	3000
Node（其他服务器）	脚本中写明的端口	脚本中的端口
Laravel	artisan 文件	8000
Bun	bun.lock / bun.lockb	—
Docker Compose	compose.yaml、docker-compose.yml…	已发布的端口

Joppa 会读取根目录以及 monorepo 中每个 workspace 的 dev 脚本。端口可以写成以下形式：--port 3000、-p 3000、--port=3000、PORT=3000、${PORT:-3000}。

推荐的子域名

如果只有一个服务器，项目会获得基础域名：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 导入。

没有检测到服务器？

手动添加域名：一个子域名（admin）或完整域名，加上一个端口。之后你随时可以在 域名 标签页中添加更多。

项目页面

添加后，项目会有自己的页面和以下标签页：

标签页	快捷键	内容
域名	D	域名、目标和状态
进程	P	由 Joppa 启动的开发服务器和容器
环境	E	已关联的服务和 .env 编辑器
运行时	R	Node、包管理器和 PHP 的版本
分析	S	流量、延迟、错误和可用性

操作 菜单（⋯）提供 重命名…（可选「同时重命名域名」）、更换图标…、在访达中显示 和 从 Joppa 移除。移除项目会停止它的开发服务器并忘记其本地配置；它的文件夹以及可能存在的 joppa.toml 不会被改动。