iris 多环境配置需分层管理：compose 文件按环境拆分（基础/开发/生产），worker 通过 env 参数区分逻辑分支，d1 数据库按环境隔离实例并前缀迁移文件，敏感配置须通过 wrangler 注入而非硬编码。
用环境变量 + 多个 Compose 文件组合切换
Iris 本身不内置多环境配置管理逻辑——它跑在 Cloudflare Worker 上，而 Worker 的环境隔离靠的是 CF_PAGES_ENVIRONMENT 或你传入的 env 参数，不是靠本地 YAML 文件。但实际项目中，你大概率会用 Docker Compose 启本地调试服务（比如 mock 工具调用、测试记忆存储），这时候多环境配置就落在 Compose 层。
常见错误是把所有配置塞进一个 docker-compose.yml，然后靠注释开关不同段落，结果一合并 PR 就冲突，一换环境就忘改某处端口或数据库名。
- 基础服务定义（如
iris-runtime容器、redis缓存）写在docker-compose.yml - 开发专用配置（如挂载源码、开启
DEBUG=true、暴露localhost:3000）放docker-compose.override.yml - 生产专用配置（如限制内存、关闭日志输出、用 D1 替代 SQLite）放
docker-compose.prod.yml - 启动时显式指定文件顺序：
docker compose -f docker-compose.yml -f docker-compose.prod.yml up
Worker 环境下用 env 参数区分逻辑分支
Cloudflare Worker 的 env 是只读对象，Iris 在初始化时会读取它来决定行为。比如你部署了两个版本：一个是 iris-dev.example.com（绑定 dev 环境变量），另一个是 iris-prod.example.com（绑定 prod）。它们共享同一份代码，但运行时表现不同。
容易踩的坑是硬编码判断字符串：if (env.ENV === 'prod')——这会让本地测试无法覆盖 prod 分支逻辑。应该把关键开关抽成可配置项：
- 用
env.MEMORY_STORE_TYPE控制状态存 KV 还是 D1 - 用
env.TOOL_TIMEOUT_MS调整工具调用超时（dev 可设 10s，prod 设 3s） - 用
env.LOG_LEVEL控制日志粒度（warn或debug） - 所有这些值在 Wrangler 配置里通过
vars或secrets注入，不写死在代码里
D1 数据库迁移要按环境拆 schema 版本
Iris 的记忆存储依赖 D1，而 D1 的 migrations 是全局的。如果你在 dev 环境跑了 migration-002.sql 加了个 tool_call_attempts 字段，但 prod 还卡在 migration-001.sql，后续写入就会报 no such column 错误。
这不是 Iris 的 bug，是 D1 的设计约束。解决方式很直接：
- 每个环境独占一个 D1 数据库实例（
iris-dev-db/iris-prod-db），别共用 - migration 文件名带上环境前缀：
dev-migration-002-add-attempts.sql，并在 Wrangler 的d1_migrations列表里按环境过滤 - CI 流程中，prod 环境只允许执行带
prod-前缀的 migration - 本地调试时用
wrangler d1 execute iris-dev-db --file=dev-migration-002.sql手动触发
别把敏感配置塞进代码或公开仓库
有些团队会把 API key、D1 DB ID 写在 iris.config.ts 里，然后 git commit。这是最典型的“环境配置泄漏”场景。Iris 运行时不会校验你是否误传了 prod key 到 dev 环境，它只会照单执行。
正确做法是全部走 Worker 的 env 注入：
WRANGLER_ENV=prod wrangler deploy --var API_KEY=$PROD_API_KEY- 本地测试用
.dev.vars文件（加到.gitignore），内容为API_KEY=xxx，然后source .dev.vars && wrangler dev - CI 中用 secret 注入，例如 GitHub Actions 的
${{ secrets.PROD_D1_DATABASE_ID }} - 代码里统一用
env.API_KEY，不 fallback 到默认值或process.env
复杂点在于 D1 的 database_id 和 database_name 必须配对，且不能在 runtime 动态解析——你得确保 env.D1_DATABASE_ID 指向的确实是 env.D1_DATABASE_NAME 对应的实例，这个映射关系只能靠部署流程保证，没法靠代码自动校验。
