dotenv-diff

扫描你的代码库，检测每一个环境变量引用。它可以帮助你在变量引发运行时错误之前，及早发现缺失、未使用、重复和误用的变量。

对 SvelteKit、Next.js 和 Nuxt 提供一流支持。同样适用于现代 JavaScript/TypeScript 项目以及 Node.js 和 Vue 等框架——或任何其他需要可靠 .env 文件比较的场景。

✨ 收录于 awesome-cli-apps - 精选的 CLI 应用列表

为什么选择 dotenv-diff？

• 确保所有必需的环境变量都已定义
• 捕获缺失或配置错误的变量
• 通过保持团队对必需变量的一致性认识来改善协作
• 降低提交敏感数据的风险
• 轻松扩展以支持 monorepo 和多环境配置

工作原理

→ 查看 功能文档，了解扫描器检查的内容及其工作原理。

配置（--init）

生成默认配置文件：

dotenv-diff --init

→ 查看 配置文档 了解更多详情。

Git hooks 和 CI/CD 集成

轻松将 dotenv-diff 集成到你的 Git hooks 或 CI/CD 流水线中，以强制执行环境变量的一致性。

→ 查看 Git Hooks 文档 了解更多详情。

框架特定警告

在 SvelteKit、Next.js 和 Nuxt 项目中，dotenv-diff 会检测框架特定的环境变量误用。

▸ Framework issues (SvelteKit)
──────────────────────────────────────────────────────────────────────
PUBLIC_API_URL              $env/dynamic/private
                            variables must not start
                            with "PUBLIC_"
                            src/routes/+page.server.ts:3
──────────────────────────────────────────────────────────────────────

→ 查看 框架文档 了解更多详情。

编写良好的 .env.example

编写一个让团队新贡献者更容易理解的 .env.example：

# Node environment (development, production, etc.)
# @optional
NODE_ENV=development

# Public API URL is used to call our backend
PUBLIC_API_URL=http://localhost:3000

# Temporary token for the partner API sandbox — ask the integrations team for a new one
# @expire 2027-03-31
PARTNER_API_TOKEN=

→ 了解更多：编写良好的 .env.example

漂移警告

扫描会将你的代码与单个文件进行比较——因此，如果你在 .env 中添加了某个键但忘记在 .env.example 中记录，直到新贡献者克隆仓库时才会被发现。漂移警告正是用来捕获这种情况的：

▸ Drift between .env and .env.example
──────────────────────────────────────────────────────────────────────
STRIPE_SECRET               not documented in .env.example
──────────────────────────────────────────────────────────────────────

默认开启；可通过 --no-drift-warnings 选择退出。

→ 查看 漂移警告 了解更多详情。

过期警告

为你的环境变量添加过期元数据，以便在它们即将过期时收到警告。例如，在你的 .env 文件中：

# @expire 2025-12-31
API_TOKEN=

→ 查看 过期文档 了解更多详情。

忽略注释

你可以通过在代码中添加注释来忽略特定的环境变量警告。例如：

const apiKey = process.env.API_KEY; // dotenv-diff-ignore

当你确定源代码中的某个特定警告是安全的时，这会很有帮助。

→ 查看 忽略注释文档 了解更多详情。

抑制现有警告（--baseline）

在已有已知警告的项目中采用 dotenv-diff 时，可以将当前状态记录到基线文件中。后续运行将只报告新引入的问题：

dotenv-diff --baseline

→ 查看 基线文档 了解更多详情。

解释变量（--explain）

检查特定的环境变量，查看其定义位置、在代码库中的使用位置以及整体状态：

dotenv-diff --explain DATABASE_URL

→ 查看 --explain 文档 了解更多详情。

Monorepo 支持

在包含多个应用和包的 monorepo 中，你可以包含共享文件夹：

{
  "scripts": {
    "dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*' --ignore VITE_MODE"
  }
}

→ 查看 Monorepo 文档 了解更多详情。

这将：

• 扫描当前应用
• 包含共享包
• 忽略仅在特定环境中使用的变量

退出代码

• 0 → 无错误
• 1 → 发现错误（或严格模式下的警告）

文档

→ 查看 dotenv-diff 文档 获取完整文档

贡献

欢迎提交 Issue 和 Pull Request。
→ 查看 CONTRIBUTING 了解详情。

感谢以下为该项目做出贡献的优秀人士：

许可证

根据 MIT 许可证授权。

由 chrilleweb 创建。