Why .env.example Gets Out of Sync — and What Actually Fixes It

说明与用途

.env.example 文件因手动维护而易失效。通过使用 env.schema.toml 作为单一真相源，生成 .env.example 并使用 EnvShield 的 pre‑commit 钩子强制同步，可防止漂移。

问题

Environment variable example files drift out of sync with code, causing runtime failures and onboarding friction.

结果

Adopting a schema‑driven approach eliminates manual maintenance of .env.example, catches drift early via pre‑commit checks, and provides type‑safe validation against code and deployment manifests.

工作流

• 1. Create or update env.schema.toml with variable definitions, types, defaults, and conditional requirements.
• 2. Run envshield schema sync to generate a fresh .env.example from the schema.
• 3. Commit the generated .env.example and the schema to version control.
• 4. Install the pre‑commit hook with envshield hook install to run envshield schema sync --check before each commit.
• 5. On pull requests, the hook ensures any changes to the schema are reflected in the example file, failing the commit if drift is detected.

证据

EnvShield takes the same schema-as-contract idea further in a different direction: the same schema also validates against a Docker Compose or Kubernetes manifest, a second service written in a different language, and the actual git history of what the contract used to require — not just a local .env file.

来源

Wire that into envshield hook install and it runs automatically before a commit lands — but only for a schema you actually staged, so it never blocks a commit that didn't touch configuration.

来源