dotenv 完全指南：用零依赖模块在 Node.js 中加载 .env 环境变量（含 CLI 与源码级解析）

开发工具后端【免费下载链接】dotenvLoads environment variables from .env for nodejs projects.项目地址https://gitcode.com/gh_mirrors/do/dotenv点击查看免费下载dotenv 是一个零依赖的 Node.js 模块用于将.env文件中的环境变量加载进process.env为核心骨架结合 lib/main.js、cli.js、lib/config-options.js 等源码与 tests/ 下的测试用例系统讲解安装接入、CLI 用法、全部配置项、解析引擎规则以及底层实现原理。读完本文你将能独立完成.env文件的创建、加载、多文件合并、调试与 CLI 注入并能按需启用fast快解析器或编写基于parse/populate的扩展插件。快速开始安装在项目根目录执行npm install dotenv --savedotenv无任何运行时依赖包体积与解析成本都保持极简见 package.json 的dependencies为空。本包自带 CLI 命令bin字段指向dist/index.cjs安装后npx dotenv或dotenv均可直接调用。创建 .env 文件在项目根目录新建.env# .env HELLODotenv OPENAI_API_KEYyour-api-key-goes-here加载并读取在应用代码中尽早导入并配置// index.js require(dotenv).config() // 或使用 ESM 方式import dotenv/config console.log(Hello ${process.env.HELLO})运行$ node index.js ◇ injected env (2) from .env Hello Dotenv◇ injected env (2) from .env是加载成功后的注入提示表示从.env中注入了 2 个变量。提示信息输出到stderr而非 stdout因此不会污染管道化的标准输出见 CHANGELOG.md v18.0.0 变更记录。从源码看加载流程在 lib/main.js 的configDotenv中实现先按默认路径path.resolve(process.cwd(), .env)解析fs.readFileSync读取文件再交给DotenvModule.parse解析最后DotenvModule.populate写入process.env并把实际写入的键值集合populated数量打印出来。CLI 用法dotenv 从 v18.0.0 起自带 CLI见 CHANGELOG.md 的 v18.0.0 条目非常适合在启动命令前注入环境变量也便于 CI、Docker 与 coding agent 使用。// index.js console.log(Hello ${process.env.HELLO})$ npx dotenv run -- node index.js ◇ injected env (2) from .env Hello Dotenv--分隔符是可选的dotenv 自己的选项必须放在命令之前命令之后的所有参数原样透传给目标命令$ dotenv run node index.js $ dotenv run -q node index.js $ dotenv run --override --debug -- node index.js $ dotenv run -f .env.local,.env node index.jsCLI 的完整入口在 cli.js 的run()函数parseRunArgs负责解析参数loadEnvFiles读取并合并各文件随后通过 lib/spawn-command.js 的spawnCommand派生子进程执行命令并把子进程的退出码原样转发见 tests/test-cli.js 中“preserves child exit code”用例。多文件加载与优先级-f/--file支持一次选择多个.env文件用逗号分隔或重复该标志均可文件按给定顺序加载$ dotenv run --file .env.local,.env node index.js ◇ injected env (2) from .env.local, .env未指定--override时先加载的值优先第一个值胜出已存在于process.env中的变量不会被覆盖指定--override时后加载的值覆盖先前的值最后一个值胜出并覆盖已存在的环境变量。CLI 在 cli.js 的loadEnvFiles中先解析各文件到临时对象parsedAll最后一次性 populate 进process.env合并顺序与override语义和 SDK 的config({ path: [...] })完全一致。退出码与文件缺失行为CLI 会转发子命令的退出状态。默认.env缺失时允许继续运行ENOENT被吞掉但用-f显式指定的文件缺失时会停止执行并报错对应 cli.js 中options.defaultPath的判断逻辑。进阶用法ES6 导入import dotenv/configDOTENV_ENCODING、DOTENV_PATH、DOTENV_QUIET、DOTENV_DEBUG、DOTENV_OVERRIDE、DOTENV_FAST为config()和dotenv run提供默认值。优先级从高到低为直接传入的选项/标志 DOTENV_*环境变量 旧的DOTENV_CONFIG_*名称。注意空值和 false 值不会触发回退到旧名称。其他包管理器bun add dotenv yarn add dotenv pnpm add dotenv deno add dotenvMonorepo 场景对于apps/backend/app.js这类结构把.env放在app.js进程实际运行的目录下即可# app/backend/.env S3_BUCKETYOURS3BUCKET SECRET_KEYYOURSECRETKEYGOESHERE因为默认路径是基于process.cwd()当前工作目录解析的。多行值从 v15.0.0 起支持多行变量例如私钥可以直接换行书写PRIVATE_KEY-----BEGIN RSA PRIVATE KEY----- ... Kh9NV... ... -----END RSA PRIVATE KEY-----也可以双引号包裹并使用\n转义PRIVATE_KEY-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END RSA PRIVATE KEY-----\n注意只有双引号包裹的值才会展开\n换行。这在 tests/test-parse.js 中有明确验证EXPAND_NEWLINESexpand\nnew\nlines会展开为真实换行而单引号或未引用的DONT_EXPAND_UNQUOTED、DONT_EXPAND_SQUOTED会保留字面\n。注释.env支持整行注释和行内注释# This is a comment SECRET_KEYYOURSECRETKEYGOESHERE # comment SECRET_HASHsomething-with-a-#-hash从 v15.0.0 起破坏性变更只要出现#即视为注释开始因此值里若含#必须用引号包裹。解析引擎Parse解析引擎可独立使用接受 String 或 Buffer返回键值对象const dotenv require(dotenv) const buf Buffer.from(BASICbasic) const config dotenv.parse(buf) // 返回对象 console.log(typeof config, config) // object { BASIC : basic }使用 dotenvx 实现变量展开、命令替换、加密与多环境以下高级能力由 dotenvx 提供dotenv本身刻意保持单文件解析、不做展开/加密变量展开引用并展开本机已有变量写入.env# .env USERNAMEusername DATABASE_URLpostgres://${USERNAME}localhost/my_database$ dotenvx run --debug -- node index.js ⟐ injected env (2) from .env · dotenvx1.59.1 DATABASE_URL postgres://usernamelocalhost/my_database命令替换把命令输出塞进变量# .env DATABASE_URLpostgres://$(whoami)localhost/my_database加密一条命令给.env文件加解密$ dotenvx set HELLO Production -f .env.production $ echo console.log(Hello process.env.HELLO) index.js $ DOTENV_PRIVATE_KEY_PRODUCTION.env.production private key dotenvx run -- node index.js ⟐ injected env (2) from .env.production · dotenvx1.59.1 Hello Production多环境按环境建文件用-f加载$ echo HELLOproduction .env.production $ dotenvx run -f.env.production -- node index.js Hello production多个.env文件时先指定的优先$ echo HELLOlocal .env.local $ echo HELLOWorld .env $ dotenvx run -f.env.local -f.env -- node index.js Hello local生产部署创建.env.production→dotenvx encrypt -f .env.production加密 → 在服务器上设置解密密钥DOTENV_PRIVATE_KEY_PRODUCTION→ 把加密后的.env.production提交进代码库并部署 → 运行时由dotenvx run -- node index.js自动解密注入。同步Syncing用dotenvx encrypt -f .env加密后随 git 安全同步解密密钥与代码分离依然符合 Twelve-Factor 原则。FAQ 速查问题结论应该提交.env文件吗不建议。除非用 dotenvx 加密加密后反而推荐提交。变量展开怎么做使用 dotenvx。要不要多个.env文件每个环境一个文件.env本地、.env.production生产避免自定义继承式配置必要时跨环境复制值。用import怎么写import dotenv/config置于读取环境变量的模块之前或dotenv run -- node index.mjs。可以写插件吗可以。dotenv.config()返回包含parsed键的对象可直接传给dotenv-expand等插件继续加工。已存在的环境变量怎么办默认绝不覆盖冲突时跳过.env中的同名项需要覆盖时用override选项。变量在 React 里不生效React 跑在 Webpack 中process.env只能通过 Webpack 配置注入react-scripts内置 dotenv 但要求变量以REACT_APP_前缀。.env加载失败多半是文件位置不对。开启debug: true查看控制台错误。报Module not found: Cant resolve os|path前端场景缺少 polyfill安装node-polyfill-webpack-plugin并在webpack.config.js中配置或直接使用 dotenv-webpack。解析引擎规则清单来自 README FAQ测试逐一验证BASICbasic→{BASIC: basic}空行跳过以#开头的行视为注释#标记注释开始值被引号包裹时除外空值变成空字符串EMPTY→{EMPTY: }保留内部引号类 JSONJSON{foo: bar}→{JSON:{\foo\: \bar\}}未引用值的两端空白被去除FOO some value→{FOO: some value}单双引号包裹的值会被脱引号SINGLE_QUOTEquoted→{SINGLE_QUOTE: quoted}单双引号包裹的值保留两端空白FOO some value →{FOO: some value }双引号值展开换行MULTILINEnew\nline→{MULTILINE: new\nline}支持反引号BACKTICK_KEYThis has single and double quotes inside of it.这些规则与 tests/.env 测试样本及 tests/test-parse.js 中的断言一一对应例如INLINE_COMMENTS、EQUAL_SIGNSequals、SPACED_KEY、export EXPORT_IS_DECLAREDparsedexport关键字会被忽略等。SDK 参考config / parse / populatedotenv 暴露三个函数config、parse、populate类型声明见 lib/main.d.ts。config()读取.env→ 解析 → 写入process.env返回包含parsed或error键的对象const result dotenv.config() if (result.error) { throw result.error } console.log(result.parsed)选项path默认path.resolve(process.cwd(), .env)指定自定义路径也支持URL对象require(dotenv).config({ path: /custom/path/to/.env }) const fileUrl new URL(file:///custom/path/to/.env) require(dotenv).config({ path: fileUrl })传数组可加载多个文件按顺序解析并与process.env或option.processEnv合并未设override时首个值胜出设了则末个值胜出require(dotenv).config({ path: [.env.local, .env] })选项quiet默认false抑制运行时日志。dotenv/config导入与 preload 方式默认即为true可用DOTENV_QUIETfalse或旧名DOTENV_CONFIG_QUIETfalse在 shell 里重新开启启动信息。require(dotenv).config({ quiet: false }) // 改为 true 可抑制输出选项encoding默认utf8指定.env文件编码require(dotenv).config({ encoding: latin1 })选项debug默认false开启日志定位键值未被按预期写入的原因require(dotenv).config({ debug: process.env.DEBUG })选项override默认false用.env的值覆盖本机已设置的环境变量多文件时配合path数组逐文件生效。未设置时首个值胜出设置后末个值胜出require(dotenv).config({ override: true })选项fast默认false启用约 2 倍速的字符扫描解析器character-scanner parser默认仍是经典正则解析器require(dotenv).config({ fast: true })选项processEnv默认process.env指定一个自定义对象作为写入目标默认写process.envconst myObject {} require(dotenv).config({ processEnv: myObject }) console.log(myObject) // 来自 .env 的值 console.log(process.env) // 未被改动parse()解析引擎独立可用接受 String 或 Buffer返回键值对象可选{ fast: true }const dotenv require(dotenv) const buf Buffer.from(BASICbasic) const config dotenv.parse(buf) console.log(typeof config, config) // object { BASIC : basic }parse支持debug选项输入不合规时会输出调试信息const dotenv require(dotenv) const buf Buffer.from(hello world) const opt { debug: true } const config dotenv.parse(buf, opt) // 因输入不是 KEYVAL 形式会看到一条 debug 消息populate()把解析结果写入目标的引擎接受 target、source 与 options适合自定义对象的高级用户const dotenv require(dotenv) const parsed { HELLO: world } dotenv.populate(process.env, parsed) console.log(process.env.HELLO) // world自定义 source 与 target并开启override与debugconst dotenv require(dotenv) const parsed { HELLO: universe } const target { HELLO: world } dotenv.populate(target, parsed, { override: true, debug: true }) console.log(target) // { HELLO: universe }populate支持两个选项debug默认false输出排查日志与override默认false是否覆盖已存在的变量。从 lib/main.js 的实现看populate逐键遍历parsed若目标对象已存在该键且override为真则覆盖否则跳过不存在的键直接写入并统计实际写入的populated集合返回。若 target/source 不是对象会抛出code为OBJECT_REQUIRED的错误对应 tests/test-populate.js 的断言。CLI 参考dotenv命令随包自带可用npx dotenv或直接在 npm scripts 中使用。run从.env加载环境变量然后运行命令npx dotenv run [options] -- command [args...]npx dotenv run -- node index.js npx dotenv run -f .env.local -- node index.js npx dotenv run -f .env.local -f .env -- npm testdotenv 选项放在命令之前--分隔符可选命令后的所有参数透传给目标命令tests/test-cli.js 验证了空格、引号、空参数与 shell 元字符的透传保真。CLI 选项表选项说明-f, --file paths加载一个或多个文件。可重复标志或用逗号分隔。默认.env。-q, --quiet抑制 “injected environment variables” 提示消息。--debug开启 debug 日志。--override覆盖已有环境变量。加载多文件时最后一个值胜出。--fast使用更快的字符扫描解析器。-h, --help显示帮助。也可用dotenv --help。未设--override时已有环境变量优先多文件间先加载的值胜出设了--override则文件值覆盖已有变量且后加载的文件覆盖先加载的。环境变量默认值表可用环境变量设置 CLI 默认值CLI 标志优先于它们变量默认说明DOTENV_PATH.env要加载的文件路径。DOTENV_ENCODINGutf8文件编码。DOTENV_QUIETfalse抑制注入提示消息。DOTENV_DEBUGfalse开启 debug 日志。DOTENV_OVERRIDEfalse覆盖已有环境变量。DOTENV_FASTfalse使用更快的解析器。旧的DOTENV_CONFIG_*名称在对应DOTENV_*未设置时作为回退。布尔类设置中false、0、no、off与空值均视为关闭。源码级原理双解析器正则解析与 fast 字符扫描lib/main.js 内置两条解析路径tests/test-parse-fast.js 专门验证 fast 模式默认parseRegexlib/main.js基于LINE正则逐行匹配KEYVAL处理export前缀、引号脱壳、双引号\n/\r展开。parseFastlib/main.js手写字符扫描器源自 PR #1010用KEY_CHAR查找表A-Za-z0-9._-扫描键名逐字符判断注释、export前缀、引号配对无正则回溯开销官方标注约 2 倍速通过{ fast: true }、CLI--fast或DOTENV_FASTtrue开启。两套解析器对同一输入产生一致结果只是性能路径不同。配置合并链路config-options.jslib/config-options.js 是配置层的枢纽parseBoolean把字符串false | 0 | no | off | 归一为false其余字符串为true非字符串走Boolean()。optionsFromEnv按ENCODING / PATH / QUIET / DEBUG / OVERRIDE / FAST顺序读取DOTENV_*缺失时回退DOTENV_CONFIG_*其中ENCODING与PATH保留字符串其余经parseBoolean转布尔。configDotenv通过{ ...optionsFromEnv(), ...options }合并环境变量提供默认值显式传入的 options 覆盖前者tests/test-config-options.js 验证了别名优先级与显式 false/空值不回退的行为。CLI 信号与进程管理cli.js 在派生子进程后做了完整的信号管理交互式终端stdin.isTTY下首次 Ctrl-C 交给前台子进程处理第二次转发SIGTERM、第三次SIGKILL非交互CI/服务场景用独立进程组SIGINT/SIGTERM/SIGHUP/SIGQUIT均转发到整个进程组避免遗留孙进程子进程退出码原样透传process.exit(exitCode)被信号终止时向自身重发信号保持退出语义。Windows 下由 lib/spawn-command.js 负责cmd.exe参数转义quoteWindowsArgument、protectShellToken、PATHEXT可执行文件解析与.bat/.cmd/npm shim 的双重转义相关行为在 tests/test-cli.js 的 Windows 用例中覆盖。类型声明lib/main.d.ts 为 TypeScript 用户提供了完整类型DotenvConfigOptionspath: string | string[] | URL、encoding、quiet、debug、override、fast、processEnv、DotenvConfigOutput{ error?, parsed? }以及parse/populate的签名类型测试见 tests/types/test.ts。相关工具dotenv-expand展开.env中的变量引用。dotenv-vscode在 VS Code 中隐藏/管理密钥。dotenvx为.env提供加密、多环境与同步能力.env.vault支持在 v18.0.0 已移除见 CHANGELOG.md。完整变更历史见 CHANGELOG.mdv18.0.0 引入 CLI 与 fast 解析器v18.0.3 修复.env内设置DOTENV_QUIET的问题v18.0.4 让import dotenv/config默认静默quiet: true。小结从.env文件的创建、config()加载、CLIdotenv run注入到parse/populate独立引擎与双解析器原理dotenv 以极小的 API 面覆盖了环境变量管理的完整闭环。实际使用建议本地/开发用.env生产单独维护.env.production并配合 dotenvx 加密遇到加载异常优先开启debug: true定位追求启动性能时启用fast解析器。仓库内 tests/ 目录保留了全部行为契约可作为深入研读的起点。赞分享开发工具后端【免费下载链接】dotenvLoads environment variables from .env for nodejs projects.项目地址https://gitcode.com/gh_mirrors/do/dotenv点击查看免费下载相关推荐python-dotenv 实战指南.env 文件解析、环境变量加载与 CLI 操作全解析python dotenv 实战指南.env 文件解析、环境变量加载与 CLI 操作全解析 python dotenv 是一个从 .env 文件读取键值对并将后端scan4all 依赖解析gotenv 库加载 .env 环境变量的完整实践指南scan4all 依赖解析gotenv 库加载 .env 环境变量的完整实践指南 导读 本指南围绕 Go 开源库 gotenv 仓库内完整源码 https:网络安全漏洞扫描渗透测试应用安全Node.js环境变量终极配置指南dotenv模块安全使用详解Node.js环境变量终极配置指南dotenv模块安全使用详解 在Node.js应用开发中环境变量配置是确保应用安全性和灵活性的关键环节。node expr后端上一篇d2s-editor5分钟掌握暗黑破坏神2存档编辑的完整指南下一篇5分钟快速上手用Markdown Viewer打造极致浏览器阅读体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考