为什么要在 HelloWorld 里做多环境变量隔离
HelloWorld 的“一键生产化”把代码直接打成镜像或 Serverless 包，如果数据库密钥、第三方 Token 写死在 main.py，镜像一旦外泄就等于把钥匙交出去。多环境变量（multi-env vars）让你在同一仓库里保存 dev/test/prod 三份配置，运行时由平台注入，既满足“本地秒起”，也保证“上线零泄露”。
从 2026.5.0 起，官方把环境变量面板拆成「Project级」与「Run级」两层：Project 级随仓库走，Run 级只在本次容器生命周期生效，后者可覆盖前者。理解这两层关系，是后续不踩坑的前提。
功能边界与兼容性速览
1. 仅支持 UTF-8 无 BOM 的 .env.* 文件，最大 64 KB/份。
2. 变量名必须与 [A-Z_][0-9A-Z_]* 正则匹配，避免带横杠或句点。
3. 桌面端（macOS/Win/Linux）与 WebIDE 行为一致；iPad 端因 WebKit 限制，hello env pull 命令需手动确认剪贴板权限。
4. Serverless Run 目前只在 AWS Lambda 层支持环境变量，边缘节点尚处于灰度，官方文档标注为“实验”。
三步完成最小可运行配置
Step 1 创建环境文件
在项目根目录新建三份文件：
├── .env.dev ├── .env.test └── .env.prod
以 Python Flask 为例，.env.dev 写：
FLASK_ENV=development DATABASE_URL=sqlite:///dev.db SECRET_KEY=dev-only-not-secret
test 与 prod 把地址换成各自 RDS 连接串，SECRET_KEY 用 32 位随机串。
Step 2 声明环境映射
HelloWorld 在 2026.5.0 引入 .hello/envmap.json（若不存在，命令行会自动生成）。最小内容：
{
"default": "dev",
"map": {
"dev": ".env.dev",
"test": ".env.test",
"prod": ".env.prod"
}
}
key 名可自定义，但建议与 Git 分支保持一致，降低心智负担。
Step 3 选择注入时机
平台提供两条路径：
- WebIDE：右上角 Run ▶ 下拉框 → Environment → 选 dev/test/prod，点击即生效。
- 本地 CLI：安装
hello命令（随桌面版捆绑）。执行hello env switch prod后，下次hello run会自动加载 .env.prod。
桌面端 vs WebIDE 最短入口对照
| 平台 | 入口 | 回退办法 |
|---|---|---|
| macOS | Menu → Run → Configure Environment → Select | rm .hello/local-env.json 后重启 IDE |
| Windows | File → Preferences → Environment Variables → Import | 删除同文件即可 |
| WebIDE | 右侧导航栏“Env”图标→下拉选择 | 刷新页面即恢复默认 |
常见分支：把敏感值挪到 Run 级
场景：开源仓库要公开 .env.prod 结构，但 JWT 密钥不能进 Git。解决：把密钥留在 HelloWorld 控制台「Project Secrets」区域，勾选「Run 级覆盖」。此时镜像构建阶段无法读到该变量，只在容器启动瞬间注入，满足“仓库公开+密钥不落地”。
cat cert-* > full.pem 合并。
回退与故障排查
现象：切换环境后变量未更新
可能原因：旧容器仍在复用。验证：底部状态栏看 Container ID 是否变化。处置：手动点击「Stop」再「Run」；或 CLI 加 --fresh 参数强制重建。
现象：Serverless Run 报 “Environment variable XXX exceeds 4 KB”
AWS Lambda 层限制。缓解：把长证书转存 S3，变量只保留 S3_URI，函数启动时下载到 /tmp。
是否值得开会员？
免费账户 Secrets 上限 10 条、Serverless Run 500 次/月。经验性观察：高校单班 30 人同时期末演示，半天就能烧完 500 次。若教学场景频繁，建议升级 Edu Plan（年费 ￥499， Secrets 无上限，Run 次数 2 万/月），成本低于自建 EC2。
不适用场景清单
- 需要动态热更新变量而不重启容器——HelloWorld 当前必须重启 Run 才能重载。
- 变量总数 > 500 条——WebIDE 下拉框会明显卡顿，可改用文件挂载方案。
- 合规要求“密钥不落盘”且“内存加密”——需改用云厂商 KMS，平台侧仅提供通用隔离。
最佳实践 6 条
- 文件名与分支同名，降低沟通成本。
- 把“是否可重建”作为准入条件：凡是无法从 env 文件重新生成的值，一律进 Secrets。
- 在 README 放一张“环境变量矩阵”截图，外部贡献者一眼看懂。
- prod 环境加
HELLO_ENV=production标记，代码里可用if os.getenv("HELLO_ENV") == "production"做二次校验。 - 每次升级 IDE 前，先把
.hello/目录加入 Git 忽略，避免本地缓存冲突。 - 定期用
hello env audit扫描未使用变量，一键清理，减少泄露面。
验证与观测方法
1. 在代码里打印 os.environ 前 5 位，确认无完整密钥落日志。
2. 构建完成后，用 docker history --no-trunc <image> | grep -i env 检查镜像层，确保无硬编码值。
3. 在 HelloWorld 控制台打开“Run Log”→“Environment”标签，平台会自动打码 Secrets 值，若仍明文显示，说明未正确标记，需重新归类。
FAQ（FAQPage Schema）
学生账号无法看到 Secrets 面板怎么办？
需教师后台勾选「AI 功能授权」；若仍失败，清除 ~/.hello/license.json 后重登即可同步权限。
能否在 .env 文件里写中文？
可以，但必须 UTF-8 无 BOM；带 BOM 会导致 HelloWorld 解析失败，表现为变量值为空。
同一项目能否同时开 dev、test 两个容器？
目前一个仓库只绑定一个活动 Run，需复制项目到不同工作区才能并行；官方称多 Run 并行已在需求池，尚未排期。
收尾：下一步行动
现在就把仓库根目录的硬编码 IP 地址拎出来，按本文模板建三份 .env 文件，再配一条 hello env switch 命令，跑通本地单元测试后，用 Serverless Run 一键丢到 AWS Lambda，确认日志无密钥明文——至此，HelloWorld 多环境变量隔离就闭环了。后续若变量膨胀，可再拆分子文件并配合 Secrets，持续把“可重建”与“不可泄露”两件事分开，你的开发-测试-生产流水线将长期保持干净、可审计、好交接。
