用AI排查环境变量，应该对照三份信息：代码实际读取什么、配置样例声明什么、目标环境实际提供了什么。优先找缺失项、名字不一致、字符串被当成布尔值，以及构建时和运行时的配置错位。只比较两份.env文件，常常看不到真正生效的值来自哪里。
项目已经在本地时，可以让墨刀AI客户端梳理代码与配置文件的对应关系。把源码、启动脚本和不含密钥的配置样例作为首轮资料，输出变量清单；真实密钥无需出现在对话、报告或新生成的文档中。
配置文件存在，不代表程序已经读取
.env.example通常是给开发者看的配置样例，单凭文件存在不能判断应用会加载它；.env是否加载、何时加载、被什么覆盖，取决于启动命令、框架和加载代码。先找程序入口，再看配置文件，比把文件逐个改名更有效。
可以先列出根目录的项目说明、依赖清单、启动脚本和配置模块。若项目还很陌生，按从入口阅读本地代码库的方法找到启动链，避免假定所有JavaScript项目都用同一种配置规则。
另外，“我电脑上能运行”可能依赖终端会话或系统里早已存在的变量。新同事复制同样文件，却没有这些隐含条件，便出现看似随机的失败。应记录变量来源，而不只记录文件里的文本。
先生成一张不含密钥的配置对照表
下面以包含Node.js服务和Vite前端的项目为例，先按读取位置整理变量。
| 变量 | 使用位置 | 预期含义 | 应核对的问题 |
|---|---|---|---|
| APP_PORT | 服务启动模块 | 监听端口，数字 | 是否为空；能否转换成合法端口；是否与现有服务冲突 |
| FEATURE_EXPORT | 导出功能开关 | true或false | 代码是否把字符串false误判为开启 |
| RETRY_LIMIT | 请求重试模块 | 允许的重试次数 | 0是否有业务含义；空值是否被错误当成0 |
| DATABASE_URL | 服务端数据连接 | 连接配置 | 只记录已配置/缺失与注入来源，不输出值 |
| VITE_API_BASE_URL | 前端请求模块 | 浏览器使用的接口地址 | 是否在对应构建模式中提供；是否指向正确环境 |
同一个变量在多个文件中读取时，要把所有位置保留在一行或同一组里。一个文件把空值当默认值，另一个文件直接报错，即使变量名一致，行为也不一致。对于动态拼接的变量名，要求AI标为“需要继续追踪”，不要假装静态搜索已经覆盖所有读取方式。
请只读分析当前项目，不打开真实密钥文件，不打印环境变量值。
读取源码、启动脚本、配置加载模块和.env.example。
列出：变量名、读取文件与符号、使用阶段、类型、默认行为、是否必填。
对照样例，找出代码读取但样例缺失、样例声明但无引用、名称疑似不一致的项。
说明各启动方式怎样加载配置；没有证据的加载顺序标为未知。
输出docs/config-map.md草稿，不修改应用逻辑或真实配置。“false”为什么仍然打开了功能
Node.js环境变量文档说明，解析得到的变量值是文本。因此字符串“false”并不会自动变成布尔值false。若代码使用Boolean(value)，非空字符串仍会得到true。
功能开关应约定允许哪些文本，并明确缺省行为。下面的小函数只接受true和false，空值按关闭处理。
function readBoolean(value) {
if (value === undefined || value.trim() === "") return false;
const normalized = value.trim().toLowerCase();
if (normalized === "true") return true;
if (normalized === "false") return false;
throw new Error("FEATURE_EXPORT must be true or false");
}在这套规则下，undefined、空字符串和“false”关闭功能，“true”开启，“0”会报错，而不是被悄悄解释成另一个含义。团队若希望接受0和1，应把它写成明确规则，并为两种值添加验证。
数字变量也一样：先判断是否缺失，再转换与检查范围。尤其要分清“没有配置重试次数”与“明确设置为0次”，因为它们可能分别代表使用默认值与关闭重试。让AI统一改成“值或默认值”，有可能把有效的0覆盖掉。
本地修改正确，线上为什么还是旧值
先判断这项配置是在构建时写入前端资源，还是在服务启动后读取。对于Vite前端，公开环境变量会参与构建；只改服务器的环境设置而不重新构建前端，不一定改变已生成的JavaScript文件。
Vite官方配置说明指出，默认情况下，VITE_前缀的变量会暴露到客户端代码；特定模式的.env文件优先于通用文件，启动进程中已存在的变量优先级更高。因此，排查时应同时确认构建模式与进程注入，而不是只盯着.env。
对本例的VITE_API_BASE_URL，可以让AI沿三步追踪：
- 找到前端请求代码读取的位置，确认名称确实相同，未同时使用另一个硬编码地址。
- 查看构建脚本采用的模式，以及该模式会读取的配置文件，检查构建环境是否另外注入同名变量。
- 核对当前部署的构建产物和构建记录，确认是否来自预期配置；修改后按项目流程重新构建和部署。
不要为了“让浏览器也能读到”而给数据库密码或服务端令牌加上VITE_前缀。前端需要公开接口地址，服务端凭证应由服务端持有。此处的判断是配置使用位置是否正确，不能靠隐藏输入框或改变量名解决。
怎样缩小两套环境的差异
“开发正常、测试失败”时，先对比变量名称、是否存在、格式与来源，再根据需要由有权限的负责人核对具体值。可以把环境清单写成下面的形式，避免把配置文件整体复制进聊天：
变量：FEATURE_EXPORT
开发环境：已配置；字符串；来自本地启动环境；期望关闭
测试环境：已配置；字符串；来自部署配置；期望关闭
实际行为：开发关闭，测试开启
读取代码：config/features.js / exportEnabled
版本差异：待核对
下一步：比较两个部署版本的布尔解析逻辑如果两边代码版本不同，就先确认行为变化；如果代码相同，再查注入来源和加载顺序。一次只改变一个已定位的问题，并记录改变前后的现象，这样才能知道哪项调整真正有效。
代码解析规则修改后，可按AI生成单元测试的方法补上缺失、空值、合法值和非法值。验证重点是业务含义是否一致，不是让程序在任何输入下都静默启动。
排查结束后留下什么
保存一份不含真实密钥的变量清单，更新必要的.env.example说明，并让启动检查在必填配置缺失时给出可理解的错误。错误信息写变量名和规则即可，不要把变量值一起打印出来。
在墨刀AI客户端里，可继续让AI对照更新后的源码重新生成配置差异摘要：哪些变量新增、哪些不再使用、哪些改变了类型或默认行为。这样交给同事的是一份可以维护的配置说明，而不是只在当前电脑上偶然跑通的环境。
