Node.js parseEnv 读取配置：井号何时成为注释，false为什么仍然是字符串
一个配置值本来含有井号，读进应用后却少了后半截；另一个开关写着false，布尔转换后却打开了功能。这两类问题处在不同层：前者由配置语法决定，后者来自应用如何解释字符串。使用原生parseEnv时，把解析与业务类型校验分开，才能定位是哪一步改变了含义。
本例在Linux、Node.js v24.19.0实跑，使用.mjs文件与内置模块，无需安装第三方包。所有数据都在内存中构造，不访问网络、不读取凭据，也不修改外部服务。文档以官方说明核对，输出来自这里标明的具体运行版本。 示例只解析公开的教学字符串；读取一个指定测试键的旧值用于前后对照，不输出任何现有环境内容。
AI生成的概念示意图：带引号护罩的纸条保留内部符号，未加护罩的纸条在注释标记处停止，表示引用决定文本边界；不是真实软件界面或运行截图。
完整程序与实际输出
保存为demo.mjs，执行node demo.mjs。代码与输出分列如下。
import { parseEnv } from 'node:util';
import assert from 'node:assert/strict';
const source = `YQ_LABEL = blue # a comment
YQ_QUOTED = "blue # keep"
YQ_PAD = ' roomy '
YQ_PORT = 3000
YQ_ENABLED = false
YQ_LINES = "first
second"
`;
const before = process.env.YQ_LABEL;
const config = parseEnv(source);
for (const key of Object.keys(config).sort()) {
console.log(key, JSON.stringify(config[key]), typeof config[key]);
}
assert.equal(config.YQ_LABEL, 'blue');
assert.equal(config.YQ_QUOTED, 'blue # keep');
assert.equal(config.YQ_PAD, ' roomy ');
assert.equal(config.YQ_ENABLED, 'false');
assert.equal(process.env.YQ_LABEL, before);
console.log('Boolean(false text):', Boolean(config.YQ_ENABLED));
console.log('explicit boolean:', config.YQ_ENABLED === 'true');
console.log('environment unchanged:', process.env.YQ_LABEL === before);本次实际标准输出：
YQ_ENABLED "false" string YQ_LABEL "blue" string YQ_LINES "first\nsecond" string YQ_PAD " roomy " string YQ_PORT "3000" string YQ_QUOTED "blue # keep" string Boolean(false text): true explicit boolean: false environment unchanged: true
井号是否在引号里会改变结果
YQ_LABEL后面的井号启动注释，最终只得到blue。YQ_QUOTED用双引号包住整个值，所以blue后面的井号与keep都保留下来。程序将每个值交给JSON.stringify显示，既能看见引号内的内容，也避免空白在网页排版中被误读。
这里采用Node.js自己定义的DotEnv语法。名为.env的文件并没有一个所有工具完全共同遵循的正式规范；跨工具迁移时，应对照实际解析器测试。不要因为某个库能读出同一份文件，就假定它与Node对所有转义、重复键和非法行都有相同处理。
空白与跨行文本也有明确边界
YQ_PAD的单引号包住两个前导和尾随空格，因此读到的值仍是带空白的roomy。键与未加引用值周围的空白则可以被忽略。若一个配置值的首尾空格属于业务内容，应通过引用明确表达，而不是依赖编辑器视觉上难以察觉的空格。
YQ_LINES的双引号跨越两行，结果含有真实换行；JSON展示时把它显示为转义形式。未经引用的值不具备同样的跨行语义。接收多行模板或说明文字时，应该针对实际读取结果做断言，避免把文件中的两行误当成两个独立配置项。
数字和布尔外观不会自动改变类型
输出中YQ_PORT是字符串3000，YQ_ENABLED是字符串false，每个条目后的typeof都为string。因此Boolean转换得到true，因为非空字符串为真；示例再通过与字符串true比较，才得到本次预期的false。解析器没有擅自决定端口或开关的业务类型。
真实开关不能只接受任何不等于true的值为false，否则拼错的tru也会被静默关闭。应先要求输入属于明确枚举，再转换。端口则需要完整数字格式、整数性与允许范围等验证；直接parseInt可能只读取前缀，仍不能作为完整校验。
先得到对象，再决定如何使用
parseEnv返回一个配置对象，没有把样本灌入process.env。程序保存某个测试键的先前值并在解析后对照，environment unchanged为true。这种分离便于先审查配置，再选择允许生效的字段，避免解析测试改变整个进程的运行环境。
部署流程还应约定默认值、环境覆盖顺序、未知键处理与缺失必填项。本文没有读取磁盘文件，也没有调用loadEnvFile，不能由此推断那些入口的覆盖行为。配置经常含有密钥，真实排错时不要照搬本例把所有值打印出来；可只报告键名、类型与是否通过校验。
参考资料与验证记录
官方资料核验于2026年10月3日。本次完整程序退出码为0，标准错误为空。
