terraform init 時，常見搜尋是「跨境拉 Provider」「TF_PLUGIN_CACHE_DIR 共用風險」「.terraform.lock.hcl 門禁」。本文含評測閾值、可複製變數與 terraform.rc、對照矩陣、FAQ；並對齊 併發寫鎖 與 二／四／八秒 流程重試。內鏈：技術部落格列表、MacPull 首頁；延伸 Helm OCI 拉取矩陣、構建池併發 FAQ。
評測維度與閾值
痛點：① 跨境 RTT 放大握手與下載成本；② 多 Pipeline 共用 TF_PLUGIN_CACHE_DIR 易撞檔案鎖；③ lockfile 與解析版本漂移。另需留意 模組來源（Git／HTTP）亦會放大網路變異，宜與 Provider 策略分開觀測。下列閾值請寫入 Runbook。
- 快取磁碟：
init前 APFS 可用 ≥12GB；不足先清子目錄或乾淨工作區。 - init 逾時：跨境外層10–20 分鐘硬逾時；逾時勿無限重試，改記錄鏡像與 digest。
- 流程重試：二／四／八秒退避、最多三次；逾六十秒仍敗則降併發或換備援鏡像。
- 併發寫快取：同機並行 Job 各用獨立
TF_PLUGIN_CACHE_DIR子路徑，避免兩條管線掃同一樹。
可執行命令／環境變數清單
憑證與鏡像 URL 放密文；terraform.rc 可預置於映像再以 TF_CLI_CONFIG_FILE 指向。需要隔離工作資料夾時可另設 TF_DATA_DIR，與快取目錄分開，降低誤刪風險。
export TF_IN_AUTOMATION=1 TF_INPUT=0
export TF_CLI_CONFIG_FILE="${HOME}/.terraformrc-ci"
export TF_PLUGIN_CACHE_DIR="${HOME}/Library/Caches/tf-plugin/${CI_JOB_ID:-local}"
mkdir -p "${TF_PLUGIN_CACHE_DIR}"
cat > "${TF_CLI_CONFIG_FILE}" <<'EOF'
provider_installation {
network_mirror {
url = "https://tf-mirror.example.com/v1/providers/"
include = ["registry.terraform.io/*/*"]
}
direct { exclude = [] }
}
credentials "app.terraform.io" { token = "REPLACE_WITH_CI_SECRET" }
EOF
# 於開發機或黃金映像產生 lock 後提交；CI 內乾跑：
terraform init -input=false -no-color
私有 Registry 時，credentials 區塊的 hostname 須與 required_providers 來源字串一致，避免默默走匿名直連。
鎖檔入庫：將 .terraform.lock.hcl 與程式碼一併版控；禁止在受保護分支默默 -upgrade；升級 Provider 走獨立 PR 以利回滾。
校驗平台：terraform providers lock 含 darwin_arm64 等目標，避免 CI 首次解析漂移。
鏡像順序：provider_installation 內排 network_mirror、filesystem_mirror、direct；跨境鏡像優先。
觀測：短期 TF_LOG=INFO 導工件；對照鏡像 access log。
門禁：fmt -check、validate、init 乾跑；PR 檢 lock 差異與權杖未入庫。
對照表或決策矩陣
| 維度 | 直連 Registry | network_mirror | filesystem_mirror |
|---|---|---|---|
| 跨境延遲 | 易受出口抖動影響 | 邊緣鏡像較穩 | 區網／本機最低 |
| 維運成本 | 低；顧配額審計 | 索引同步 | 批次同步目錄 |
| lockfile | digest 變動頻 | 與直連一致最佳 | 缺版硬失敗 |
| 併發鎖 | 獨立 cache 目錄 | 鏡像扛 QPS | 唯讀掛載＋本機 cache |
| 場景 | 內網低延遲 | 跨境主力 | 離線映像 |
filesystem_mirror 常見作法是將套件樹同步至內網唯讀掛載，仍以本機 TF_PLUGIN_CACHE_DIR 承接執行期熱檔；與 Helm OCI 拉取矩陣相同，請把 digest 稽核 與 出站白名單 一併納入合規清單。
FAQ
為何 init 偶發「快取損毀」或卡住？
多為共用 cache 根目錄或碟滿。改每 CI_JOB_ID 子資料夾並監控空間；敗後刪子樹單次重試，勿並行寫同樹。
鏡像回 403／簽章不符怎麼辦？
核對 credentials 與鏡像前綴；比 lock hashes 與鏡像 digest。仍敗暫切 direct 並寫工件供資安複核。
需要開 TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE 嗎？
受保護流水線勿常態開；升級走獨立變更單。救災限分支並於合併前還原旗標。