Back to Details

env-var-hygiene

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Environment Variable Hygiene

环境变量规范管理

Best practices for managing environment variables across deployment platforms.
跨部署平台管理环境变量的最佳实践。

Triggers

触发场景

Invoke when user mentions:
  • "env var", "environment variable", "production deploy"
  • "webhook secret", "API key", "token"
  • "Invalid character in header", "ERR_INVALID_CHAR"
  • "silent failure", "webhook not working"
  • "Vercel", "Convex", "deployment", "secrets"
当用户提及以下内容时适用：
  • "env var"、"environment variable"（环境变量）、"production deploy"（生产环境部署）
  • "webhook secret"（Webhook密钥）、"API key"（API密钥）、"token"（令牌）
  • "Invalid character in header"（请求头存在无效字符）、"ERR_INVALID_CHAR"
  • "silent failure"（静默失败）、"webhook not working"（Webhook无法正常工作）
  • "Vercel"、"Convex"、"deployment"（部署）、"secrets"（保密信息）

Core Principles

核心原则

1. Trailing Whitespace Kills

1. 尾随空格是隐形杀手

Env vars with 
\n
or trailing spaces cause cryptic errors:
  • "Invalid character in header content" (HTTP headers)
  • Webhook signature mismatch
  • Silent authentication failures
Root Cause: Copy-paste or 
echo
introduces invisible characters.
Prevention:
bash
undefined
带有
\n
或尾随空格的环境变量会导致难以排查的错误：
  • HTTP请求头报错“Invalid character in header content”
  • Webhook签名不匹配
  • 认证静默失败
根本原因： 复制粘贴或
echo
命令会引入不可见字符。
预防方案：
bash
undefined

✅ Use printf, not echo

✅ 使用printf而非echo

printf '%s' 'sk_live_xxx' | vercel env add STRIPE_SECRET_KEY production
printf '%s' 'sk_live_xxx' | vercel env add STRIPE_SECRET_KEY production

✅ Trim when setting

✅ 设置时去除多余字符

npx convex env set --prod KEY "$(echo 'value' | tr -d '\n')"
npx convex env set --prod KEY "$(echo 'value' | tr -d '\n')"

❌ Don't use echo directly

❌ 不要直接使用echo

echo "sk_live_xxx" | vercel env add KEY production # May add \n
undefined
echo "sk_live_xxx" | vercel env add KEY production # 可能会添加\n
undefined

2. Cross-Platform Parity

2. 跨平台一致性

Shared tokens (webhook secrets, auth tokens) must be identical across platforms:
  • Vercel ↔ Convex
  • Frontend ↔ Backend
  • Dev ↔ Staging ↔ Prod (within each platform)
Common Pitfall: Set token on one platform, forget the other.
Prevention:
bash
undefined
共享令牌（如Webhook密钥、认证令牌）必须在所有平台保持一致：
  • Vercel ↔ Convex
  • 前端 ↔ 后端
  • 开发环境 ↔ 预发布环境 ↔ 生产环境（同一平台内）
常见误区： 在一个平台设置了令牌，却忘记在其他平台同步。
预防方案：
bash
undefined

Generate token once

一次性生成令牌

TOKEN=$(openssl rand -hex 32)
TOKEN=$(openssl rand -hex 32)

Set on ALL platforms

在所有平台设置

npx convex env set --prod CONVEX_WEBHOOK_TOKEN "$(printf '%s' "$TOKEN")" printf '%s' "$TOKEN" | vercel env add CONVEX_WEBHOOK_TOKEN production
undefined
npx convex env set --prod CONVEX_WEBHOOK_TOKEN "$(printf '%s' "$TOKEN")" printf '%s' "$TOKEN" | vercel env add CONVEX_WEBHOOK_TOKEN production
undefined

3. Validate Format Before Use

3. 使用前验证格式

API keys have specific formats. Validate before deployment:
ServicePatternExample
Stripe Secret
sk_(test|live)_[A-Za-z0-9]+
sk_live_xxx
Stripe Public
pk_(test|live)_[A-Za-z0-9]+
pk_live_xxx
Stripe Webhook
whsec_[A-Za-z0-9]+
whsec_xxx
Stripe Price
price_[A-Za-z0-9]+
price_xxx
Clerk Secret
sk_(test|live)_[A-Za-z0-9]+
sk_live_xxx
API密钥有特定格式，部署前需验证：
服务格式规则示例
Stripe Secret
sk_(test|live)_[A-Za-z0-9]+
sk_live_xxx
Stripe Public
pk_(test|live)_[A-Za-z0-9]+
pk_live_xxx
Stripe Webhook
whsec_[A-Za-z0-9]+
whsec_xxx
Stripe Price
price_[A-Za-z0-9]+
price_xxx
Clerk Secret
sk_(test|live)_[A-Za-z0-9]+
sk_live_xxx

4. Dev ≠ Prod

4. 开发环境≠生产环境

Separate deployments have separate env var stores:
  • Setting 
    .env.local
    doesn't affect production
  • Convex dev and prod are separate deployments
  • Vercel has per-environment variables
Always verify prod separately:
bash
undefined
不同部署环境拥有独立的环境变量存储：
  • 设置
    .env.local
    不会影响生产环境
  • Convex的开发和生产环境是独立部署实例
  • Vercel支持按环境配置变量
务必单独验证生产环境：
bash
undefined

Convex

Convex

npx convex env list --prod
npx convex env list --prod

Vercel

Vercel

vercel env ls --environment=production
undefined
vercel env ls --environment=production
undefined

5. CLI Environment Gotcha

5. CLI环境的陷阱

CONVEX_DEPLOYMENT=prod:xxx npx convex data
may return dev data.
Always use explicit flags:
bash
undefined
使用
CONVEX_DEPLOYMENT=prod:xxx npx convex data
可能返回开发环境数据。
始终使用显式标志：
bash
undefined

❌ Unreliable

❌ 不可靠

CONVEX_DEPLOYMENT=prod:xxx npx convex data
CONVEX_DEPLOYMENT=prod:xxx npx convex data

✅ Reliable

✅ 可靠

npx convex run --prod module:function npx convex env list --prod
undefined
npx convex run --prod module:function npx convex env list --prod
undefined

Quick Reference

快速参考

Setting Env Vars Safely

安全设置环境变量

Convex:
bash
undefined
Convex：
bash
undefined

Dev

开发环境

npx convex env set KEY "value"
npx convex env set KEY "value"

Prod (use --prod flag)

生产环境（使用--prod标志）

npx convex env set --prod KEY "$(printf '%s' 'value')"

**Vercel:**
```bash
npx convex env set --prod KEY "$(printf '%s' 'value')"

**Vercel：**
```bash

Production

生产环境

printf '%s' 'value' | vercel env add KEY production
printf '%s' 'value' | vercel env add KEY production

With explicit environment

指定环境

vercel env add KEY production --force
undefined
vercel env add KEY production --force
undefined

Checking Env Vars

查看环境变量

Convex:
bash
npx convex env list           # dev
npx convex env list --prod    # prod
Vercel:
bash
vercel env ls                              # all
vercel env ls --environment=production     # prod only
Convex：
bash
npx convex env list           # 开发环境
npx convex env list --prod    # 生产环境
Vercel：
bash
vercel env ls                              # 所有环境
vercel env ls --environment=production     # 仅生产环境

Detecting Issues

问题检测

Trailing whitespace:
bash
undefined
尾随空格检测：
bash
undefined

Check Convex prod

检查Convex生产环境

npx convex env list --prod | while IFS= read -r line; do if [[ "$line" =~ [[:space:]]$ ]]; then echo "WARNING: $(echo "$line" | cut -d= -f1) has trailing whitespace" fi done

**Format validation:**
```bash
npx convex env list --prod | while IFS= read -r line; do if [[ "$line" =~ [[:space:]]$ ]]; then echo "WARNING: $(echo "$line" | cut -d= -f1) has trailing whitespace" fi done

**格式验证：**
```bash

Validate Stripe key format

验证Stripe密钥格式

value=$(npx convex env list --prod | grep "^STRIPE_SECRET_KEY=" | cut -d= -f2-) [[ "$value" =~ ^sk_(test|live)_[A-Za-z0-9]+$ ]] || echo "Invalid format"
undefined
value=$(npx convex env list --prod | grep "^STRIPE_SECRET_KEY=" | cut -d= -f2-) [[ "$value" =~ ^sk_(test|live)_[A-Za-z0-9]+$ ]] || echo "Invalid format"
undefined

References

参考资料

See 
references/
directory:
  • format-patterns.md
    - Regex patterns for common services
  • platform-specifics.md
    - Vercel, Convex, Railway platform details
  • hygiene-checklist.md
    - Pre-deployment validation checklist
  • parity-verification.md
    - Cross-platform token verification
请查看
references/
目录：
  • format-patterns.md
    - 常见服务的正则格式规则
  • platform-specifics.md
    - Vercel、Convex、Railway等平台的详细配置说明
  • hygiene-checklist.md
    - 部署前验证清单
  • parity-verification.md
    - 跨平台令牌一致性校验指南

Related Commands

相关命令

  • /pre-deploy
    - Comprehensive pre-deployment checklist
  • /env-parity-check
    - Cross-platform token verification
  • /stripe-check
    - Stripe-specific environment audit
Based on 2026-01-17 incident: Trailing 
\n
in 
STRIPE_SECRET_KEY
caused "Invalid character in header" error. Token mismatch between Vercel and Convex caused silent webhook failures.
  • /pre-deploy
    - 全面的部署前检查清单
  • /env-parity-check
    - 跨平台令牌一致性校验
  • /stripe-check
    - Stripe专属环境配置审计
基于2026-01-17的故障案例：
STRIPE_SECRET_KEY
中的尾随
\n
导致“Invalid character in header”错误；Vercel与Convex间的令牌不匹配导致Webhook静默失败。