Coolify 的 Laravel 配置最佳实践：env() 边界、密钥加密、环境判断与常量规范化

本文围绕 Coolify 仓库中 Laravel Best Practices 技能的配置规则 展开，系统讲解 env() 与 config() 的职责边界、生产密钥的加密与外部化方案、环境判断的规范写法，以及魔法字符串常量化与语言文件的取舍。读完本文，你可以直接对照 Coolify 的 config/services.php、config/app.php 等真实配置，掌握一套可落地、可自查的 Laravel 配置规范。

规则定位：laravel-best-practices 技能的第 7 条规则

这份配置规则并非孤立存在，而是 Coolify 内置的 AI 辅助技能 laravel-best-practices 的一部分。该技能面向"编写、审查或重构 Laravel PHP 代码"的场景（控制器、模型、迁移、Form Request、Policy、Job 等），并按影响面将规则分成 19 个主题文件（rules/ 目录下从数据库性能、缓存到路由、架构、风格各有专篇）。

在 SKILL.md 的快速参考中，配置类规则被列为第 7 条，浓缩为三句话：

• env() 只允许出现在 config 文件中；
• 环境判断用 App::environment() 或 app()->isProduction()；
• 用 config、语言文件和常量取代硬编码文本。

同时该技能强调"Consistency First（一致性优先）"原则：应用规则前先检查代码库既有模式，与现有约定保持一致比套用理论最优解更重要。下面的每一条规则在 Coolify 仓库自身代码中都有对应的实例可以印证。

规则一：env() 只允许出现在配置文件中

为什么直接调用 env() 是危险的

规则原文（rules/config.md）给出的理由是：配置被缓存后，env() 可能返回 null。具体来说，Laravel 通过 php artisan config:cache 把整个配置树序列化为 bootstrap/cache/config.php 静态文件；此后请求启动时不再读取 .env，任何散落在业务代码里的 env('XXX') 调用都拿不到值——开发环境正常、一上生产就出问题的隐蔽 bug 大多源于此。

错误的写法：

$key = env('API_KEY');

正确的写法：

// config/services.php
'key' => env('API_KEY'),

// 应用代码中
$key = config('services.key');

关键不在"哪里调用"，而在"值在哪个时点被读取"：env() 只应在配置文件加载阶段执行一次，之后所有业务代码一律通过 config() 读取已物化的值。

Coolify 仓库的实际做法

用正则在整个 app/ 目录下搜索 env('...') 的直接调用，结果为 0 处——Coolify 自身严格遵循了这一条规则。第三方服务凭证全部集中在 config/services.php 中声明，例如：

// config/services.php
'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
    'scheme' => 'https',
],
'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
],

这个文件还体现了两个细节：

1. env() 的第二参数即默认值，如 env('MAILGUN_ENDPOINT', 'api.mailgun.net')，保证未配置该变量时服务仍可工作；
2. 非机密常量直接硬编码，如 'scheme' => 'https'，没有必要让不可变的值走环境变量。

config/app.php 同样遵循该模式：应用名称 env('APP_NAME', 'Coolify')、运行环境 env('APP_ENV', 'production')、调试开关 (bool) env('APP_DEBUG', false)、加密密钥 env('APP_KEY') 等全部收敛在配置文件中，且显式类型转换（如 (bool)）避免了字符串 "0" 被当作 truthy 的经典坑。

从源码结构看，Coolify 还注册了一个专门的配置访问层：ConfigurationServiceProvider 将 ConfigurationRepository 绑定为单例并注入 config 实例，业务代码通过该 Repository 统一读写配置，进一步把"配置访问"从散落的 config() 调用中收拢起来。

规则二：使用加密环境变量或外部密钥管理

规则要求：永远不要把生产环境的明文密钥提交进版本库或放进 .env 文件里共享。

反例（把 .env 提交到仓库或粘贴到聊天软件中）：

STRIPE_SECRET=sk_live_abc123
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI

正例（Laravel 提供的加密环境变量命令）：

# 加密生产环境文件（--readable 使密文保持可读性、行内保留）
php artisan env:encrypt --env=production --readable

# 需要排障时解密
php artisan env:decrypt --env=production

对云端部署，规则进一步建议优先使用平台原生的密钥存储（如 AWS Secrets Manager、HashiCorp Vault 等），在运行时注入，而不是随镜像或仓库分发。

与 Coolify 场景的关联

Coolify 本身是一个自托管 PaaS，其部署形态以 Docker Compose 为主（仓库根目录提供 docker-compose.yml、docker-compose.prod.yml 等文件），.env 通常只存在于宿主机、不进入仓库。这一部署方式天然规避了"明文 .env 被提交"的风险，但规则给出的加密方案对仓库维护者同样有用：当需要把一份配置快照交给 CI 或团队共享时，env:encrypt 可以把敏感项变成密文。Coolify 自身配置中的敏感项（如 config/services.php 里的 domain_connect.private_key）都通过环境变量注入而非写死在代码中，与该规则精神一致。

规则三：环境判断使用 App::environment()

直接写 env('APP_ENV') === 'production' 与规则一同源：一旦 config:cache 生效，APP_ENV 环境变量在运行期可能已被"消费"或不可见，比较结果不可靠。规范写法是：

// 错误
if (env('APP_ENV') === 'production') { ... }

// 正确
if (app()->isProduction()) { ... }

// 或
if (App::environment('production')) { ... }

App::environment() / app()->isProduction() 读取的是启动时已缓存的 config('app.env')，语义上与配置缓存机制完全兼容。

Coolify 仓库的实例位于 AppServiceProvider：在 boot() 中用 App::isProduction() 判断环境再决定是否启用生产模式行为（见 app/Providers/AppServiceProvider.php 第 35、49 行附近的两次判断）。这正是规则所要求"通过应用实例而非 env() 判断环境"的落地方式。

规则四：用常量与语言文件替代硬编码魔法字符串

规则要求：模型的状态、类型、状态码等，应使用类常量而不是裸字符串字面量：

// 错误
return $this->type === 'normal';

// 正确
return $this->type === self::TYPE_NORMAL;

常量化带来三个实际收益：IDE 自动补全与重构安全、拼写错误在编译期暴露（self::TYPE_NROMAL 会直接报错）、取值范围一目了然。

Coolify 的做法是在 app/Enums/ 目录下用 PHP 枚举集中定义各类取值，例如 ActivityTypes、ApplicationDeploymentStatus、ProcessStatus、ProxyTypes、Role 等——相比纯类常量，enum 还附带类型系统与 cases() 枚举能力，是该规则的现代实现。

对于用户可见文案，规则给出了一个务实的边界条件：

// 仅当项目已在使用语言文件时才引入 __()
return back()->with('message', __('app.article_added'));

即：如果应用已经用语言文件做多语言，则用户可见字符串应走 __()；但不要为了纯英文应用凭空引入语言文件——简单字符串字面量即可。Coolify 显然属于前者：仓库根目录的 lang/ 目录包含 en.json、zh-cn.json、ja.json 等 18 个语种的翻译文件，其界面文案普遍通过语言键引用，符合"既然已有多语言体系，就一律走 __()"的要求。

小结：一条可执行的自查清单

把 rules/config.md 的四条规则合并，日常 Code Review 中可以用以下清单快速核对（均以 Coolify 仓库为参照）：

检查项	判定标准	Coolify 参照
env() 是否只出现在 config/ 下	app/ 等目录中 env('...') 直接调用数应为 0	grep env( 全目录为 0 处
敏感值是否硬编码或明文入库	密钥只经环境变量/外部密钥注入	config/services.php
环境判断写法	只用 App::environment() / app()->isProduction() / App::isProduction()	app/Providers/AppServiceProvider.php
魔法字符串是否常量化/枚举化	状态、类型走常量或 enum	app/Enums/
用户可见文案是否走语言文件（前提是项目已有多语言）	已有 lang/ 体系则用 __()	lang/ 18 个语种文件

最后需要重申技能文档本身的元规则：以上四条是"尚无既定模式时的默认值"。如果你的代码库（如 Coolify）已经形成了自己的约定——比如用 enum 代替类常量、用 ConfigurationRepository 统一配置访问——优先保持一致性，而不是机械套用另一套"理论上更好"的写法。