 收敛、密钥管理与枚举常量的工程规范)
Coolify 的 Laravel 配置最佳实践env() 收敛、密钥管理与枚举常量的工程规范【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文对应的工程规范原文位于 .claude/skills/laravel-best-practices/rules/config.md是 Coolify 仓库内置的 Laravel 编码规范skill中关于「配置管理」的核心规则。Coolify 本身即是一个基于 Laravel 构建的自托管 PaaS 应用本文以该规范为骨架结合仓库中真实存在的 config 文件、Action 类与枚举实现讲解如何把env()严格限定在配置文件、如何在自托管场景下管理生产密钥、如何用App::environment()判断运行环境以及如何用枚举与语言文件消灭魔法字符串。一、为什么 Coolify 需要一套配置规范Coolify 是一个大型 Laravel 单体应用包含数十个模型、数十个 Livewire 组件、数百个队列任务与命令行命令可从 app 目录的Models/、Livewire/、Jobs/、Console/Commands/等子目录一览规模。配置项横跨 SSH 连接、Docker 引擎、代理Proxy、Webhook、云厂商凭证等多个维度。这类应用的配置层一旦失控——在业务代码里到处直接调用env()、把明文密钥写进版本库、用env(APP_ENV)做环境判断——轻则在执行php artisan config:cache后读取到null导致功能静默失效重则造成生产凭据泄露。为此仓库在.claude/skills/laravel-best-practices下维护了一套按主题拆分的规范文档其中 config.md 专门约束配置相关代码的写法而总纲 SKILL.md 开篇强调了一个总原则——一致性优先Consistency FirstBefore applying any rule, check what the application already does… These rules are defaults for when no pattern exists yet, not overrides.也就是说下面四条规则适用于「代码库尚无先例」的新代码若已有先例则先跟随既有模式。理解这一点才能正确地把规范落地到 Coolify 的日常开发中。二、规则一env()只允许出现在配置文件2.1 为什么这是硬性约束规范原文给出的理由非常直接Directenv()calls may returnnullwhen config is cached.Laravel 在部署阶段常执行php artisan config:cache把所有 config 文件中的取值烘焙成一份缓存。此后业务代码再去读取.env时如果该值没有被映射进某个 config 文件env()就可能拿不到值而返回null具体行为取决于 PHP 运行环境中$_ENV/getenv()的可用性与 Laravel 对 putenv 的开关。因此业务代码必须统一从「配置中心」config()读取而config()的值又只能由配置文件这一层从env()获取。2.2 反例与正例规范给出的对照如下。反例——业务代码直接读.env$key env(API_KEY); // 配置缓存后可能返回 null正例——把读取收敛进config/services.php业务代码统一用config()// config/services.php key env(API_KEY), // Application code $key config(services.key);2.3 Coolify 中的落地证据Coolify 对这条规则的贯彻非常彻底。仓库把绝大多数自定义配置收拢进了 config/constants.php文件里几乎每一行都遵循「env()加默认值兜底」的写法。例如版本号、自托管开关与基础路径coolify [ version env(COOLIFY_VERSION) ?: 4.3.15, helper_version 1.0.16, self_hosted env(SELF_HOSTED, true), autoupdate env(AUTOUPDATE), base_config_path env(BASE_CONFIG_PATH, /data/coolify), ],而 SSH 多路复用mux这类「运行期可调」的行为参数同样以env()带默认值的形式沉淀在配置层并且直接写明了单位与语义注释ssh [ mux_enabled env(MUX_ENABLED, env(SSH_MUX_ENABLED, true)), mux_persist_time env(SSH_MUX_PERSIST_TIME, 3600), mux_lock_ttl env(SSH_MUX_LOCK_TTL, 30), // lock auto-release, seconds mux_lock_timeout env(SSH_MUX_LOCK_TIMEOUT, 10), // max wait for lock, seconds connection_timeout 10, ],在 config/constants.php 里甚至还能看到env()之间相互组合的用法例如镜像地址由REGISTRY_URL推导进一步说明「配置文件是唯一可以接触环境变量的层」。业务代码侧则严格走config()。以 app/Actions/Server/UpdateCoolify.php 为例其核心方法反复通过config(constants.coolify.version)读取当前版本并参与version_compare升级判断见该文件第 47–86 行全程没有出现一次裸env()if ($cacheVersion version_compare($cacheVersion, config(constants.coolify.version), )) { // ... current_version config(constants.coolify.version),同样地第三方服务凭据GitHub、GitLab、Stripe、各 OAuth 厂商等全部在 config/services.php 中登记——它保留了 Laravel 默认的 mailgun/postmark/ses 区块又追加了authentik、clerk、google、zitadel等 OAuth 提供方配置每个字段都是env(XXX_CLIENT_ID)形式authentik [ base_url env(AUTHENTIK_BASE_URL), client_id env(AUTHENTIK_CLIENT_ID), client_secret env(AUTHENTIK_CLIENT_SECRET), redirect env(AUTHENTIK_REDIRECT_URI), ],落地检查清单新建代码前先问三个问题——①这个值是否已被某个 config 文件收编②是否给env()传了默认值或?:回退保证未配置时行为可预期③业务类中是否只出现config(...)三、规则二生产密钥绝不落入明文.env3.1 规范原文的立场Never store production secrets in plain.envfiles in version control.git历史一旦收录过明文密钥即使后来删除泄露面也已形成。规范列举了反例# .env committed to repo or shared in Slack STRIPE_SECRETsk_live_abc123 AWS_SECRET_ACCESS_KEYwJalrXUtnFEMI3.2 自托管与云端两种解法解法 A使用 Laravel 内置的加密 env 机制。规范给出的命令是php artisan env:encrypt --envproduction --readable php artisan env:decrypt --envproductionenv:encrypt会把对应环境的.env加密为.env.encrypted--readable表示使用无分隔符的编码以便在 CI/CD 中安全传递之后应用在启动时自动解密加载只有掌握密钥LARAVEL_ENV_ENCRYPTION_KEY的进程才能读取真实值。这在把配置交付到不可信通道时尤其有价值。解法 B使用平台原生密钥管理服务。规范明确建议For cloud deployments, prefer the platforms native secret store (AWS Secrets Manager, Vault, etc.) and inject at runtime.即在云端部署时优先使用 AWS Secrets Manager、HashiCorp Vault 等托管密钥库在运行时把密钥以环境变量的方式注入容器仓库中永远只保留变量名占位。3.3 与 Coolify 的关联Coolify 本身是自托管 PaaS生产环境通常以 Docker 容器运行可参考 docker-compose.prod.yml。对这类部署形态密钥的最佳注入点就是编排层把.env中的敏感项改为「从宿主环境或密钥系统传入的运行时环境变量」让容器进程在启动那一刻才拿到真实值。这与规范「inject at runtime」的取向一致。此外代码库在模型层的敏感字段上也体现了相同的安全哲学——即使数据进了数据库也不能明文躺着。例如 app/Casts/EncryptedArrayCast.php 提供了加密数组 Cast历史迁移 2024_09_16_111428_encrypt_existing_private_keys.php 还对存量 SSH 私钥执行过一次整体加密迁移。这与「密钥不进明文.env」互为补充前者管运行时注入后者管持久化存储。实践要点.env必须进入.gitignore仓库中最多保留.env.example形式的占位模板生产凭据Stripe、云厂商 API Key、SSH 私钥、OAuth Secret永远以运行时注入或加密文件方式交付若确需在命令执行前手动解密把env:decrypt限定在受控的发布流程中并确保解密产物不入库。四、规则三环境判断统一走App::environment()判断「当前是不是生产环境」时规范明确禁止直接读env(APP_ENV)原因与规则一相同——env()在配置缓存场景下不可靠。反例if (env(APP_ENV) production) {正例两种等价写法跟随代码库既有风格二选一if (app()-isProduction()) { // or if (App::environment(production)) {App::environment()读取的是 Laravel 容器已加载的应用环境状态来源于 config 层解析后的app.env而不是在运行时二次穿透.env因此语义更稳定还支持多值判断如App::environment(local, testing)。在 Coolify 这类拥有多环境部署本地开发、自托管生产、云端 SaaS的项目里统一这类判断还能避免「同一套代码在不同环境下分支行为不一致」的隐患。延伸提示仓库的规范体系里还有更多环境相关约束例如 rules/scheduling.md 提到用environments()把计划任务限定在特定环境编写涉及环境差异的功能时可以一并查阅这些兄弟规则而不是散落地内联env()判断。五、规则四用类常量、枚举与语言文件取代魔法字符串5.1 类常量消灭裸字符串比较规范给出的对照示例// Incorrect return $this-type normal; // Correct return $this-type self::TYPE_NORMAL;把状态、类型、角色这类有限取值提升为具名常量能显著提升可读性与可重构性——拼写错误会在编译/静态分析期暴露而不再是在运行时静默返回 false。5.2 Coolify 更进一步原生枚举取代类常量值得强调的是Coolify 的代码库实际选择了比「类常量」更强的方案PHP 8.1 原生 backed enum。仓库在 app/Enums 下维护了大量状态枚举例如构建方式枚举 app/Enums/BuildPackTypes.phpenum BuildPackTypes: string { case NIXPACKS nixpacks; case STATIC static; case DOCKERFILE dockerfile; case DOCKERCOMPOSE dockercompose; case RAILPACK railpack; }部署状态枚举 app/Enums/ApplicationDeploymentStatus.phpenum ApplicationDeploymentStatus: string { case QUEUED queued; case IN_PROGRESS in_progress; case FINISHED finished; case FAILED failed; case CANCELLED_BY_USER cancelled-by-user; }此外还有NewDatabaseTypes、ProxyTypes、RedirectTypes、ProcessStatus、StaticImageTypes、Role等同族枚举见 app/Enums。相比裸字符串与类常量枚举把「合法取值集合」收进类型系统函数参数可以直接做BuildPackTypes类型约束switch/match 穷尽性检查能在编译期发现遗漏分支未来新增取值时改动集中在单个文件。对新增代码的建议当值域与业务状态机相关时优先在app/Enums下新建 backed enum 并沿用「大写下划线命名 数据库存小写串」的既有惯例只有当值域极小、仅属单一类内部实现细节时才退回类常量。5.3 语言文件仅在项目已有 i18n 时使用规范对语言文件的态度非常务实If the application already uses language files for localization, use__()for user-facing strings too. Do not introduce language files purely for English-only apps — simple string literals are fine there.即不要为了「规范而规范」去给纯英文应用凭空引入语言文件只有项目已经具备本地化基础设施时才对用户可见文案使用翻译函数// Only when lang files already exist in the project return back()-with(message, __(app.article_added));这一前提条件对 Coolify 是成立的仓库根目录维护着完整的 lang 多语言目录除lang/en下的 PHP 语言文件外还随包提供了en.json、zh-cn.json、zh-tw.json、de.json、fr.json、ja.json等十余份 JSON 翻译文件。因此在 Coolify 中给用户可见文案编写代码时应优先查询语言文件是否已有对应翻译键再决定用__()/trans()还是直接写字面量并始终与相邻代码保持一致呼应 Consistency First。六、把规范变成可执行的代码评审清单综合 config.md 四条规则与总纲 SKILL.mdCoolify 场景下的配置类代码评审可收敛为以下检查项检查点判定标准仓库参考env()调用位置只允许出现在config/下的文件config/constants.php、config/services.php业务代码取值方式一律config(...)禁止裸env()app/Actions/Server/UpdateCoolify.php 中config(constants.coolify.version)的用法默认值兜底关键配置用env(X, default)或env(X) ?: fallbackconfig/constants.php 中mux_persist_time、base_config_path等生产密钥不入库、不进明文.env运行时注入或env:encryptdocker-compose.prod.yml敏感字段加密 Cast app/Casts/EncryptedArrayCast.php环境判断使用app()-isProduction()/App::environment()—状态/类型取值优先 backed enumapp/Enums退而求其次类常量app/Enums/BuildPackTypes.php 等用户可见文案仅当语言文件已存在时使用__()lang 目录下的 JSON/PHP 翻译文件四条规则的共同底层逻辑其实只有一句话让「可变的外部输入环境变量」在唯一可信的边界config 层完成解析与默认值兜底然后让整个应用只与结构化的、类型化的内部契约打交道。无论密钥如何注入、环境如何切换业务代码面对的始终是稳定的config()结果、明确的枚举取值与统一的环境判断 API——这正是大型 Laravel 应用如 Coolify 这类部署编排平台保持可维护性的根基。七、延伸阅读规范原文与全套主题规则.claude/skills/laravel-best-practices/rules/config.md、SKILL.md含 Quick Reference 与 Consistency First 原则与配置强相关的兄弟规则security.md.env不入库、config()读密钥、敏感字段encryptedcast、architecture.md、scheduling.md仓库内配置层源码config/constants.php、config/services.php、bootstrap/app.php枚举落地实例app/Enums敏感数据持久化安全app/Casts/EncryptedArrayCast.php 与 database/migrations 下的加密迁移【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Coolify 的 Laravel 配置最佳实践：env() 收敛、密钥管理与枚举常量的工程规范
Coolify 的 Laravel 配置最佳实践env() 收敛、密钥管理与枚举常量的工程规范【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文对应的工程规范原文位于 .claude/skills/laravel-best-practices/rules/config.md是 Coolify 仓库内置的 Laravel 编码规范skill中关于「配置管理」的核心规则。Coolify 本身即是一个基于 Laravel 构建的自托管 PaaS 应用本文以该规范为骨架结合仓库中真实存在的 config 文件、Action 类与枚举实现讲解如何把env()严格限定在配置文件、如何在自托管场景下管理生产密钥、如何用App::environment()判断运行环境以及如何用枚举与语言文件消灭魔法字符串。一、为什么 Coolify 需要一套配置规范Coolify 是一个大型 Laravel 单体应用包含数十个模型、数十个 Livewire 组件、数百个队列任务与命令行命令可从 app 目录的Models/、Livewire/、Jobs/、Console/Commands/等子目录一览规模。配置项横跨 SSH 连接、Docker 引擎、代理Proxy、Webhook、云厂商凭证等多个维度。这类应用的配置层一旦失控——在业务代码里到处直接调用env()、把明文密钥写进版本库、用env(APP_ENV)做环境判断——轻则在执行php artisan config:cache后读取到null导致功能静默失效重则造成生产凭据泄露。为此仓库在.claude/skills/laravel-best-practices下维护了一套按主题拆分的规范文档其中 config.md 专门约束配置相关代码的写法而总纲 SKILL.md 开篇强调了一个总原则——一致性优先Consistency FirstBefore applying any rule, check what the application already does… These rules are defaults for when no pattern exists yet, not overrides.也就是说下面四条规则适用于「代码库尚无先例」的新代码若已有先例则先跟随既有模式。理解这一点才能正确地把规范落地到 Coolify 的日常开发中。二、规则一env()只允许出现在配置文件2.1 为什么这是硬性约束规范原文给出的理由非常直接Directenv()calls may returnnullwhen config is cached.Laravel 在部署阶段常执行php artisan config:cache把所有 config 文件中的取值烘焙成一份缓存。此后业务代码再去读取.env时如果该值没有被映射进某个 config 文件env()就可能拿不到值而返回null具体行为取决于 PHP 运行环境中$_ENV/getenv()的可用性与 Laravel 对 putenv 的开关。因此业务代码必须统一从「配置中心」config()读取而config()的值又只能由配置文件这一层从env()获取。2.2 反例与正例规范给出的对照如下。反例——业务代码直接读.env$key env(API_KEY); // 配置缓存后可能返回 null正例——把读取收敛进config/services.php业务代码统一用config()// config/services.php key env(API_KEY), // Application code $key config(services.key);2.3 Coolify 中的落地证据Coolify 对这条规则的贯彻非常彻底。仓库把绝大多数自定义配置收拢进了 config/constants.php文件里几乎每一行都遵循「env()加默认值兜底」的写法。例如版本号、自托管开关与基础路径coolify [ version env(COOLIFY_VERSION) ?: 4.3.15, helper_version 1.0.16, self_hosted env(SELF_HOSTED, true), autoupdate env(AUTOUPDATE), base_config_path env(BASE_CONFIG_PATH, /data/coolify), ],而 SSH 多路复用mux这类「运行期可调」的行为参数同样以env()带默认值的形式沉淀在配置层并且直接写明了单位与语义注释ssh [ mux_enabled env(MUX_ENABLED, env(SSH_MUX_ENABLED, true)), mux_persist_time env(SSH_MUX_PERSIST_TIME, 3600), mux_lock_ttl env(SSH_MUX_LOCK_TTL, 30), // lock auto-release, seconds mux_lock_timeout env(SSH_MUX_LOCK_TIMEOUT, 10), // max wait for lock, seconds connection_timeout 10, ],在 config/constants.php 里甚至还能看到env()之间相互组合的用法例如镜像地址由REGISTRY_URL推导进一步说明「配置文件是唯一可以接触环境变量的层」。业务代码侧则严格走config()。以 app/Actions/Server/UpdateCoolify.php 为例其核心方法反复通过config(constants.coolify.version)读取当前版本并参与version_compare升级判断见该文件第 47–86 行全程没有出现一次裸env()if ($cacheVersion version_compare($cacheVersion, config(constants.coolify.version), )) { // ... current_version config(constants.coolify.version),同样地第三方服务凭据GitHub、GitLab、Stripe、各 OAuth 厂商等全部在 config/services.php 中登记——它保留了 Laravel 默认的 mailgun/postmark/ses 区块又追加了authentik、clerk、google、zitadel等 OAuth 提供方配置每个字段都是env(XXX_CLIENT_ID)形式authentik [ base_url env(AUTHENTIK_BASE_URL), client_id env(AUTHENTIK_CLIENT_ID), client_secret env(AUTHENTIK_CLIENT_SECRET), redirect env(AUTHENTIK_REDIRECT_URI), ],落地检查清单新建代码前先问三个问题——①这个值是否已被某个 config 文件收编②是否给env()传了默认值或?:回退保证未配置时行为可预期③业务类中是否只出现config(...)三、规则二生产密钥绝不落入明文.env3.1 规范原文的立场Never store production secrets in plain.envfiles in version control.git历史一旦收录过明文密钥即使后来删除泄露面也已形成。规范列举了反例# .env committed to repo or shared in Slack STRIPE_SECRETsk_live_abc123 AWS_SECRET_ACCESS_KEYwJalrXUtnFEMI3.2 自托管与云端两种解法解法 A使用 Laravel 内置的加密 env 机制。规范给出的命令是php artisan env:encrypt --envproduction --readable php artisan env:decrypt --envproductionenv:encrypt会把对应环境的.env加密为.env.encrypted--readable表示使用无分隔符的编码以便在 CI/CD 中安全传递之后应用在启动时自动解密加载只有掌握密钥LARAVEL_ENV_ENCRYPTION_KEY的进程才能读取真实值。这在把配置交付到不可信通道时尤其有价值。解法 B使用平台原生密钥管理服务。规范明确建议For cloud deployments, prefer the platforms native secret store (AWS Secrets Manager, Vault, etc.) and inject at runtime.即在云端部署时优先使用 AWS Secrets Manager、HashiCorp Vault 等托管密钥库在运行时把密钥以环境变量的方式注入容器仓库中永远只保留变量名占位。3.3 与 Coolify 的关联Coolify 本身是自托管 PaaS生产环境通常以 Docker 容器运行可参考 docker-compose.prod.yml。对这类部署形态密钥的最佳注入点就是编排层把.env中的敏感项改为「从宿主环境或密钥系统传入的运行时环境变量」让容器进程在启动那一刻才拿到真实值。这与规范「inject at runtime」的取向一致。此外代码库在模型层的敏感字段上也体现了相同的安全哲学——即使数据进了数据库也不能明文躺着。例如 app/Casts/EncryptedArrayCast.php 提供了加密数组 Cast历史迁移 2024_09_16_111428_encrypt_existing_private_keys.php 还对存量 SSH 私钥执行过一次整体加密迁移。这与「密钥不进明文.env」互为补充前者管运行时注入后者管持久化存储。实践要点.env必须进入.gitignore仓库中最多保留.env.example形式的占位模板生产凭据Stripe、云厂商 API Key、SSH 私钥、OAuth Secret永远以运行时注入或加密文件方式交付若确需在命令执行前手动解密把env:decrypt限定在受控的发布流程中并确保解密产物不入库。四、规则三环境判断统一走App::environment()判断「当前是不是生产环境」时规范明确禁止直接读env(APP_ENV)原因与规则一相同——env()在配置缓存场景下不可靠。反例if (env(APP_ENV) production) {正例两种等价写法跟随代码库既有风格二选一if (app()-isProduction()) { // or if (App::environment(production)) {App::environment()读取的是 Laravel 容器已加载的应用环境状态来源于 config 层解析后的app.env而不是在运行时二次穿透.env因此语义更稳定还支持多值判断如App::environment(local, testing)。在 Coolify 这类拥有多环境部署本地开发、自托管生产、云端 SaaS的项目里统一这类判断还能避免「同一套代码在不同环境下分支行为不一致」的隐患。延伸提示仓库的规范体系里还有更多环境相关约束例如 rules/scheduling.md 提到用environments()把计划任务限定在特定环境编写涉及环境差异的功能时可以一并查阅这些兄弟规则而不是散落地内联env()判断。五、规则四用类常量、枚举与语言文件取代魔法字符串5.1 类常量消灭裸字符串比较规范给出的对照示例// Incorrect return $this-type normal; // Correct return $this-type self::TYPE_NORMAL;把状态、类型、角色这类有限取值提升为具名常量能显著提升可读性与可重构性——拼写错误会在编译/静态分析期暴露而不再是在运行时静默返回 false。5.2 Coolify 更进一步原生枚举取代类常量值得强调的是Coolify 的代码库实际选择了比「类常量」更强的方案PHP 8.1 原生 backed enum。仓库在 app/Enums 下维护了大量状态枚举例如构建方式枚举 app/Enums/BuildPackTypes.phpenum BuildPackTypes: string { case NIXPACKS nixpacks; case STATIC static; case DOCKERFILE dockerfile; case DOCKERCOMPOSE dockercompose; case RAILPACK railpack; }部署状态枚举 app/Enums/ApplicationDeploymentStatus.phpenum ApplicationDeploymentStatus: string { case QUEUED queued; case IN_PROGRESS in_progress; case FINISHED finished; case FAILED failed; case CANCELLED_BY_USER cancelled-by-user; }此外还有NewDatabaseTypes、ProxyTypes、RedirectTypes、ProcessStatus、StaticImageTypes、Role等同族枚举见 app/Enums。相比裸字符串与类常量枚举把「合法取值集合」收进类型系统函数参数可以直接做BuildPackTypes类型约束switch/match 穷尽性检查能在编译期发现遗漏分支未来新增取值时改动集中在单个文件。对新增代码的建议当值域与业务状态机相关时优先在app/Enums下新建 backed enum 并沿用「大写下划线命名 数据库存小写串」的既有惯例只有当值域极小、仅属单一类内部实现细节时才退回类常量。5.3 语言文件仅在项目已有 i18n 时使用规范对语言文件的态度非常务实If the application already uses language files for localization, use__()for user-facing strings too. Do not introduce language files purely for English-only apps — simple string literals are fine there.即不要为了「规范而规范」去给纯英文应用凭空引入语言文件只有项目已经具备本地化基础设施时才对用户可见文案使用翻译函数// Only when lang files already exist in the project return back()-with(message, __(app.article_added));这一前提条件对 Coolify 是成立的仓库根目录维护着完整的 lang 多语言目录除lang/en下的 PHP 语言文件外还随包提供了en.json、zh-cn.json、zh-tw.json、de.json、fr.json、ja.json等十余份 JSON 翻译文件。因此在 Coolify 中给用户可见文案编写代码时应优先查询语言文件是否已有对应翻译键再决定用__()/trans()还是直接写字面量并始终与相邻代码保持一致呼应 Consistency First。六、把规范变成可执行的代码评审清单综合 config.md 四条规则与总纲 SKILL.mdCoolify 场景下的配置类代码评审可收敛为以下检查项检查点判定标准仓库参考env()调用位置只允许出现在config/下的文件config/constants.php、config/services.php业务代码取值方式一律config(...)禁止裸env()app/Actions/Server/UpdateCoolify.php 中config(constants.coolify.version)的用法默认值兜底关键配置用env(X, default)或env(X) ?: fallbackconfig/constants.php 中mux_persist_time、base_config_path等生产密钥不入库、不进明文.env运行时注入或env:encryptdocker-compose.prod.yml敏感字段加密 Cast app/Casts/EncryptedArrayCast.php环境判断使用app()-isProduction()/App::environment()—状态/类型取值优先 backed enumapp/Enums退而求其次类常量app/Enums/BuildPackTypes.php 等用户可见文案仅当语言文件已存在时使用__()lang 目录下的 JSON/PHP 翻译文件四条规则的共同底层逻辑其实只有一句话让「可变的外部输入环境变量」在唯一可信的边界config 层完成解析与默认值兜底然后让整个应用只与结构化的、类型化的内部契约打交道。无论密钥如何注入、环境如何切换业务代码面对的始终是稳定的config()结果、明确的枚举取值与统一的环境判断 API——这正是大型 Laravel 应用如 Coolify 这类部署编排平台保持可维护性的根基。七、延伸阅读规范原文与全套主题规则.claude/skills/laravel-best-practices/rules/config.md、SKILL.md含 Quick Reference 与 Consistency First 原则与配置强相关的兄弟规则security.md.env不入库、config()读密钥、敏感字段encryptedcast、architecture.md、scheduling.md仓库内配置层源码config/constants.php、config/services.php、bootstrap/app.php枚举落地实例app/Enums敏感数据持久化安全app/Casts/EncryptedArrayCast.php 与 database/migrations 下的加密迁移【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考