应使用 terraform show -json 导出标准 JSON 解析 state，而非直接读取 terraform.tfstate；需适配 state v4 结构，注意 resources 顶层字段、敏感输出处理及禁止手动写入文件。
直接读 terraform.tfstate 文件会出错，因为它是 JSON 但带注释
官方 terraform.tfstate 默认是“pretty-printed JSON”，但 Terraform 1.0+ 实际写入时可能含行内注释（比如 // generated by Terraform），标准 System.Text.Json 或 Newtonsoft.Json 会直接抛 JsonReaderException。这不是编码问题，是格式不合规。
实操建议：
- 用
terraform show -json命令导出纯净 JSON：它把当前 state 转成标准 JSON 流，无注释、无换行干扰，且兼容所有 Terraform 版本（包括 1.5+ 的 state v4） - 不要直接
File.ReadAllText("terraform.tfstate")后丢给JsonSerializer.Deserialize<T>()—— 即使文件看起来“能打开”，反序列化大概率失败 - 如果必须离线解析（比如无
terraformCLI 环境），先用正则删掉//.*$行尾注释 +/\*[\s\S]*?\*/块注释，再 parse；但这是权宜之计，terraform show -json更稳
TerraformState 类型定义要匹配 state v4 结构，不是套用老教程的 v3 模型
Terraform 1.5 引入 state v4，核心变化：资源列表从 modules[0].resources 移到 resources 顶层字段，且每个资源带 provider_schema_version 和 schema_version；旧代码按 modules 遍历会漏资源甚至空引用。
实操建议：
- 优先参考官方 OpenAPI schema：
https://github.com/hashicorp/terraform/blob/main/internal/states/statefile/format_v4.go，别抄博客里过时的 POC 类 - 关键字段必须包含：
version（int）、terraform_version（string）、serial（long）、resources（List<Resource>）、outputs（Dictionary<string, OutputValue>） -
Resource中的instances是List<Instance>，每个Instance含attributes（JsonElement类型，别硬转成Dictionary<string, string>—— 嵌套结构会丢）
修改后写回 state 必须用 terraform apply -refresh-only 或 terraform state replace-provider，不能手写文件
直接 File.WriteAllText("terraform.tfstate", JsonSerializer.Serialize(state)) 写入，会导致 checksum 不匹配、Terraform 后续命令拒绝加载，报错 state file does not contain a valid state 或 checksum mismatch。Terraform 对 state 文件做了 SHA256 校验，且 v4 还校验 serial 递增性。
实操建议：
- 所有“修改”本质是间接操作：用
terraform state mv/rm/replace-provider等子命令，由 Terraform 自己更新文件并维护一致性 - 若需批量替换资源 ID（比如迁移模块路径），写 shell 脚本调
terraform state mv，而非 C# 解析-改-写；C# 只负责生成迁移列表或校验逻辑 - 真要注入新资源（极少见），走
terraform import，而不是往resources列表里塞对象再写文件
读取 output 值时注意 sensitive 字段和 type 动态性
从 outputs 里取值，看似简单：state.Outputs["db_url"].Value.GetString()。但实际常遇到 NullReferenceException 或类型转换失败 —— 因为 OutputValue 里 Value 是 JsonElement，而 sensitive: true 的 output，Value 是 null，真实值藏在 Sensitive 字段（bool）和 Type 字段（string）里。
实操建议：
- 安全读法：
output.Sensitive ? "(sensitive)" : (output.Value.ValueKind == JsonValueKind.Null ? "(unknown)" : output.Value.ToString()) -
Type字段标明了输出类型（"string"、"list"、"map"），但不是 JSON type，而是 HCL 类型；list(string)在 JSON 里仍是 array，但元素可能是 null，需逐个判空 - 别假设所有 output 都已计算完成：
output.Type == "string"但output.Value.ValueKind == JsonValueKind.Undefined，说明还没apply，此时读不到值
C# 解析 tfstate 不是“读个 JSON”那么简单，真正卡点永远在版本差异、敏感字段处理、以及——你根本不能自己写回文件。
