环境变量

环境 标签页（E）管理项目的 .env。Joppa 会在其中写入两类内容：你的域名的 HTTPS 地址，以及已关联服务的 连接信息。一切都要经过你确认的 diff。

接入服务

服务区块列出了 Joppa 中的服务。使用 PostgreSQL（或 Redis、Mailpit…）会打开一个 diff，并提供两个选项：

• 关联并写入 .env：写入该服务的变量，并在其端口变化时保持更新。
• 关联但不写入：Joppa 记住这个关联，但不改动文件。

对于数据库，如果项目的数据库尚不存在，Joppa 会创建它。一个项目每种类型只使用一个服务：接入 MySQL 会替换 PostgreSQL。

停止使用… 则相反：取消关联并清理 .env 会恢复 .env.example 中的值（或移除该变量），取消关联，不改动 .env 则保持文件原样。你手动修改过的变量会被保留。

变量名

Joppa 会以项目已在读取的名称写入：先是 .env 中的名称，然后是 .env.example 中的名称（即使被注释掉）。它能识别许多别名（DATABASE_URL、DIRECT_URL、POSTGRES_PRISMA_URL、POSTGRES_*、PG*、MYSQL_*…），并保留你现有 URL 的协议和参数。

如果项目没有声明任何变量，Joppa 会使用其框架的常用名称：

服务	Laravel	其他
数据库	DB_CONNECTION、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD	DATABASE_URL（Symfony：带 ?serverVersion=…&charset=utf8）
Redis、Valkey	REDIS_HOST、REDIS_PASSWORD、REDIS_PORT	REDIS_URL
Mailpit	MAIL_MAILER=smtp、MAIL_HOST、MAIL_PORT…	Symfony MAILER_DSN · Rails SMTP_ADDRESS、SMTP_PORT · Django EMAIL_HOST、EMAIL_PORT · Node SMTP_HOST、SMTP_PORT
Meilisearch	MEILISEARCH_HOST、MEILISEARCH_KEY、SCOUT_DRIVER	Symfony MEILISEARCH_URL、MEILISEARCH_API_KEY
Typesense	TYPESENSE_*、SCOUT_DRIVER	TYPESENSE_HOST、TYPESENSE_PORT、TYPESENSE_PROTOCOL、TYPESENSE_API_KEY

框架通过其文件识别：Laravel（artisan）、Symfony、Django（manage.py）、Rails、Node（package.json）。

HTTPS 地址

任何 http://localhost:PORT（或 127.0.0.1、[::1]）形式的值，只要其端口有对应的域名，就会变成相应的 HTTPS 地址，逗号分隔的列表也不例外：

- APP_URL=http://localhost:8000
+ APP_URL=https://myproject.test
- CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+ CORS_ORIGINS=https://app.myproject.test,http://localhost:3000

.env.example 中存在但 .env 中缺少的默认值也会同样处理。

由 Joppa 管理

由 Joppa 管理 区块汇总了 Joppa 要写入的变量：待更新 和 已是最新。应用（N） 会打开 diff 并写入文件。

.env 编辑器

可以直接在 Joppa 中编辑该文件。由 Joppa 管理的行会带有标记。

• / 或 ⌘ F：在文件中搜索。
• .env.example 中有、此处缺少：缺少的键的列表，以及 + 添加缺少的键（添加在 # 来自 .env.example (Joppa) 下方）。
• ⌘ S：检查并保存，附带 diff。
• 如果在你编辑期间文件在磁盘上被修改，Joppa 会提示你。

如果没有 .env，Joppa 会在保存时创建一个。

Joppa 的保证

• 写入前始终显示 diff。
• 备份：首次写入时，原始文件会被复制到 .env.joppa-backup。
• 精确修改：只有相关的行会改变；注释、export、行尾备注和多行值都保持原样。新键会添加在文件末尾的一条注释下方（# PostgreSQL (Joppa)）。