Terraform項目文件結構：從單文件到模塊化

剛接觸Terraform時，幾乎所有教程都會讓你把所有資源塞進一個main.tf文件。這確實降低了學習門檻——你不需要考慮文件放在哪、怎么命名、誰先加載。但一旦項目規模擴大，單文件的弊端立刻暴露：代碼冗長難讀、多人協作沖突頻發、資源定位困難。

本文基于HashiCorp官方建議，拆解Terraform項目的標準文件結構，以及背后的設計邏輯。

根模塊與文件加載機制

Terraform項目的根目錄被稱為"根模塊"（root module）。這里有一個關鍵認知：Terraform對文件名沒有強制規定。你完全可以把所有配置寫進hello.tf，系統照樣能跑。

真正決定文件命運的，是Terraform的加載規則：

? 當前目錄下所有.tf后綴文件都會被讀取

? 按字典序（字母順序）加載

? 最終合并為單一配置

這意味著文件命名只影響加載順序，不影響功能。但順序在某些場景下至關重要——比如變量定義必須在引用之前被加載。這也是variables.tf、locals.tf等命名慣例的由來：確保關鍵配置優先就位。

推薦文件結構

一個成熟項目的根模塊通常長這樣：

project-root/

├── backend.tf # 后端狀態存儲配置

├── provider.tf # 云服務商配置

├── variables.tf # 輸入變量聲明

├── locals.tf # 本地值定義

├── main.tf # 核心資源定義

├── vpc.tf # 網絡相關資源

├── security.tf # 安全組、網絡ACL

├── compute.tf # 計算實例、自動擴縮容

├── storage.tf # 對象存儲、塊存儲

├── database.tf # 數據庫服務

├── outputs.tf # 輸出值定義

├── terraform.tfvars # 變量實際賦值

└── README.md # 項目文檔

main.tf的角色值得單獨說明。它通常存放核心資源定義，但有兩種分化路徑：一是保持"大雜燴"，所有資源集中管理；二是按資源類型拆分為s3.tf、vpc.tf、ec2.tf等獨立文件。后者在資源數量膨脹時更清晰，但也可能帶來文件碎片化的問題。

terraform.tfvars的處理是安全紅線。這個文件存放變量的實際值，往往包含訪問密鑰、數據庫密碼等敏感信息。標準做法是：提交terraform.tfvars.example作為模板，真實.tfvars文件加入.gitignore，絕不入倉。

.gitignore必備清單

版本控制排除項需要覆蓋以下類別：

? .terraform/目錄——插件、模塊緩存、元數據

? *.tfstate及*.tfstate.backup——狀態文件（可能含敏感數據）

? .terraform.lock.hcl——提供商依賴鎖定文件

? *.log——崩潰日志等

? terraform.tfvars及*.tfvars.json——變量賦值文件

狀態文件的特殊性在于：它記錄了基礎設施的完整映射，包括資源ID、連接字符串等。即使使用遠程后端（如S3），本地運行仍可能生成臨時狀態文件，必須隔離。

多環境管理的結構選擇

當項目跨越dev、staging、prod多個環境時，文件結構的復雜度陡增。常見的組織模式包括：

文件夾隔離：每個環境獨立目錄，各自維護完整配置。優勢是環境間完全解耦，變更風險可控；代價是代碼重復，更新需多位置同步。

工作空間（workspace）：單一代碼庫，通過terraform workspace切換環境。減少重復代碼，但狀態管理更復雜，誤操作可能影響生產。

模塊封裝：將可復用資源抽離為模塊，環境目錄僅保留調用配置。這是規模化團隊的主流選擇，平衡了復用性與隔離性。

選擇哪種模式，取決于團隊規模、變更頻率和合規要求。沒有銀彈，但有一個共識：環境差異必須通過代碼顯式表達，而非依賴人工記憶或本地配置。

從"能跑"到"可維護"

文件結構的演進，本質是控制復雜度的過程。單文件階段關注"功能正確"，模塊化階段關注"變更安全"。Terraform的靈活性既是優勢也是陷阱——它允許你隨意組織，卻不保證你的組織方式能應對六個月后的需求。

HashiCorp的建議之所以成為行業慣例，并非因為強制力，而是因為它們經過了大規模實踐的篩選。當你猶豫vpc.tf和network.tf哪個命名更好時，選擇社區共識能降低協作成本。這比追求"最優"命名更有價值。