dotenv 值被 # 静默截断？.env 变量加双引号包裹
在开发 AI运营 时遇到此问题——基于大语言模型的智能分析，自动洞察市场趋势、用户行为、销售数据，提供精准运营策略。
TL;DR
dotenv 把未加引号的值中 # 当作行内注释。KEY=value#hash 实际加载的值是 value，#hash 被丢弃且无任何报错。解法：.env 中含 #、空格、特殊字符的值，一律用双引号包裹 —— KEY="value#hash"。
问题现象
后端调用上游服务，一直返回 401 Invalid credentials：
POST /api/v1/dag/trigger → 500
日志堆栈：Airflow JWT auth failed (401): {"detail":"Invalid credentials"}
at getJwtToken (airflow-client.ts)
排查发现 .env 文件中写的密码是 24 位、含 # 和 &：
AIRFLOW_PASSWORD=ooGR0^kThVI&ag#RyCpUmbIr
但 Node.js 进程实际加载到的 process.env.AIRFLOW_PASSWORD 长度只有 10，#RyCpUmbIr 整段消失。用 CLAUDE.md 记录的完整密码直接 curl 上游鉴权接口 → 返回 201；用 .env 解析出来的残缺值 → 返回 401。密码账号没问题，是 .env 加载出来的值被截断了。
根因
dotenv 沿用 shell 习惯，把未加引号的值中 # 之后的内容视为行内注释：
# .env
AIRFLOW_PASSWORD=ooGR0^kThVI&ag#RyCpUmbIr
# dotenv 实际解析为：
# AIRFLOW_PASSWORD = "ooGR0^kThVI&ag"
# #RyCpUmbIr ← 被丢弃
这个行为符合 dotenv 文档，但没有任何警告或日志，运行时拿到的就是个静默截断的字符串。叠加 &、空格、$ 等字符的 shell 转义语义，问题更隐蔽：
| 字符 | 未加引号时的行为 |
|---|---|
# | 之后内容当行内注释，截断 |
(空格) | 之后内容被丢弃 |
$VAR | 触发变量展开（可能为空字符串） |
& | shell 后台符号，在 dotenv 中通常保留但在 shell 拼接命令时再次踩坑 |
JWT_SECRET、API_KEY、DATABASE_URL 这类强随机串经常包含 #，是高发雷区。
解决方案
把 .env 中含特殊字符的值用双引号包裹：
# .env
AIRFLOW_PASSWORD="ooGR0^kThVI&ag#RyCpUmbIr"
JWT_SECRET="abc#def$ghi jkl"
DATABASE_URL="postgres://user:p@ss#word@host:5432/db"
重启服务使新值生效：
# pm2
pm2 restart analytics-api --update-env
# docker compose
docker compose restart api
# systemd
sudo systemctl restart api
为什么有效：dotenv 看到双引号包裹后，会按字面值读取到右引号为止，#、空格、$ 都不会被特殊处理（除非显式开启 expand 选项）。改完后立即验证加载结果：
// 启动时验证关键变量长度，提前拦截截断
const required = ['AIRFLOW_PASSWORD', 'JWT_SECRET', 'DATABASE_URL'] as const;
for (const key of required) {
const v = process.env[key];
if (!v || v.length < 16) {
throw new Error(`${key} 未正确加载（长度 ${v?.length ?? 0}），请检查 .env 引号`);
}
}
这样把 dotenv 的静默失败转成启动失败，下次踩坑时第一时间暴露。
注意事项
- 单引号也能用，但 dotenv 在单引号内不展开
$VAR，双引号会展开。涉及密码通常希望字面值，建议双引号 + 不写${...}。 - dotenv 版本：v15+ 默认行为如上；早期版本（v8 之前）对
#的处理略有差异，升级前先看 CHANGELOG。 - Docker / Kubernetes Secret：通过
environment:注入的变量不走 dotenv，不受此坑影响；只有.env文件、dotenv.config()路径才受影响。 - CI 环境：GitHub Actions、GitLab CI 把 secret 注入到
env上下文，也不走 dotenv。
常见问题
为什么 .env 中含 # 的密码会变短？
dotenv 默认把 # 之后的内容当作行内注释丢弃。未加引号的值 KEY=value#hash 实际加载为 value，没有报错也没有日志。把值用双引号包裹 KEY="value#hash" 即可保留完整内容。
dotenv 不生效怎么排查？
三步：先确认 dotenv.config() 在所有 import 之前执行（ES Module 的 import 是静态提升的，详见 JWT 签名静默失败排查）；再确认 .env 值不含未转义的 # 或空格；最后在进程启动后打印 process.env.XXX 的长度与字符，与 .env 源文件逐一比对。