Terraform新手咨询：内部Modules目录的最优存放结构

作为常年和Terraform打交道的老玩家，我太懂你这种纠结了——官方文档的示例往往偏向单环境场景，但实际做多环境部署时，共享模块的维护才是真正影响效率的核心问题。

先直接给结论：业内绝大多数多环境Terraform项目，都会把共享的modules目录和各环境根目录放在同级，而不是每个环境目录下单独放一份模块。下面给你拆解原因和具体实践：

两种结构的对比 #

1. 官方文档的「环境内模块」结构（不推荐多环境场景） #

就是你说的每个dev/staging/prod根目录下都有自己的modules子目录，这种结构只适合各环境差异极大，完全不需要共享模块的极端场景——比如dev用的是一套极简资源，prod是完全不同的架构。但缺点也很明显：

• 重复代码多，修改一个模块要在三个环境里同步改，极易出错
• 难以保证各环境的资源配置一致性，时间久了dev和prod的基础设施会越来越脱节

2. 行业主流的「同级共享模块」结构（强烈推荐） #

这种结构把所有通用模块抽出来放在顶层，各环境目录只负责自己的配置和资源引用，目录结构大概是这样：

your-terraform-project/
├── modules/
│   ├── vpc/               # 通用VPC模块（含子网、安全组等）
│   ├── app-server/        # 通用应用服务器模块
│   ├── managed-db/        # 托管数据库模块（适配RDS/Cloud SQL等）
│   └── monitoring/        # 监控告警模块
├── environments/
│   ├── dev/
│   │   ├── main.tf        # 引用modules里的资源，定义dev特有配置
│   │   ├── variables.tf   # dev环境的变量定义
│   │   └── terraform.tfvars # dev的具体变量值（比如实例类型t2.micro）
│   ├── staging/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── terraform.tfvars
│   └── production/
│       ├── main.tf
│       ├── variables.tf
│       └── terraform.tfvars

这种结构的核心优势：

• 单一数据源：模块只维护一份，修改一次所有环境都能复用，彻底解决重复代码问题
• 环境隔离清晰：每个环境目录只放该环境的专属配置（比如实例规格、副本数、域名），不会和模块逻辑混在一起
• 灵活适配差异：通过模块的变量参数，就能实现同一模块在不同环境的差异化部署——比如dev用单节点数据库，prod用多节点高可用集群，不需要修改模块本身

额外的实践建议 #

为了让这个结构更稳定，还有几个细节要注意：

• 给模块加版本控制：用Git tag给modules里的每个模块打版本（比如v1.0.0），各环境目录引用模块时指定版本号，避免dev环境的模块更新意外影响prod的稳定运行
• 模块参数化要彻底：尽量把所有可能的环境差异都做成变量，比如实例类型、磁盘大小、是否启用备份等，不要在模块里写死配置
• 特殊场景的局部定制：如果某个环境需要对模块做小范围定制，不要直接修改共享模块，而是在环境目录里写局部模块（比如dev/modules/custom-app-server），或者通过变量覆盖、嵌套模块的方式实现

关于官方文档的补充说明 #

官方文档里的「环境内模块」更多是为了展示单环境项目的完整结构，方便新手理解模块和根模块的关系。但在实际的多环境生产场景中，同级共享模块是行业共识，几乎所有大厂的Terraform基础设施代码都是这么组织的。

内容的提问来源于stack exchange，提问作者Shaun Croucher