Infracost v2.18.2 配置参数详解

目标：系统梳理 Infracost CLI v2.18.2 的全部配置面——命令行参数（全局 flags 与 scan/diff 专属 flags）、infracost.yml 仓库配置文件（autodetect/projects 两大块与模板语法）、CI/CD 集成配置，并给出可直接落地的 monorepo 生产配置模板。所有 flags 与回显均在 Ubuntu 24.04 + Infracost 2.18.2 实测取得；infracost.yml 参数说明经官方 Config file 文档实查（2026-10-25）并与本机 CLI 行为交叉核对。

一、环境信息

安装与凭据初始化方法见《Infracost v2.18.2 安装指南》；本文所有子命令的完整参数面与实测回显见《Infracost v2.18.2 常用 CLI 命令详解》。

二、前置条件

1. 已按安装指南完成 CLI 安装（infracost --version 回显 2.18.2）；
2. 已执行 infracost auth login（或 device flow）落盘凭据——v2 的扫描/组织类命令在无凭据时直接拦截进入登录引导，配置文件解析发生在凭据校验之后（本机实测：在演示工程放置一个故意写坏的 infracost.yml 后执行 infracost scan，输出仍是登录引导 URL 而非 YAML 报错）；
3. 理解本文配置示例的载体：一个 Terraform 工程 /root/demo-terraform，main.tf 内容：

provider "aws" {
  region = "us-east-1"
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.medium"

  tags = {
    Name = "infracost-demo-web"
  }
}

resource "aws_s3_bucket" "logs" {
  bucket = "infracost-demo-logs-q1w2e3r4"
}

三、参数查看与修改方式

Infracost v2 的配置分四个层次，优先级从高到低（云端 Org/Repo 设置高于仓库内文件，来源：官方 Config file 文档 Source Control Integrations 节，2026-10-25 实查）：

安装健康与配置合法性自查（实测回显）：

infracost doctor

Infracost Doctor 2.18.2 - running 7 checks

Authentication
  ✗  No credentials found
     →  Run `infracost auth login` to authenticate
  ⊘  Token valid
     →  skipped (No credentials found)
  ⊘  Organization accessible
     →  skipped (No credentials found)
  ⊘  API reachable
     →  skipped (Organization accessible)

CLI
  ✔  Version 2.18.2 (latest)

Configuration
  ✔  Config file valid
  !  Default org set
     →  No organization data available

  ✔  2 passed  !  1 warning  ✗  1 issue  ⊘  3 skipped

Run infracost doctor --fix to attempt auto-remediation
Info: 1 health check(s) failed

Configuration → Config file valid 即配置自检项；完成登录后复跑，凭据四项会依次点亮为 ✔。

⚠️ 环境变量边界（重要）：v2 不再读取 INFRACOST_API_KEY 环境变量——本机以 INFRACOST_API_KEY=<任意值> infracost doctor 实测，凭据检查项仍报 No credentials found。v0.x 时代「export 一个 API key 走天下」的用法在 v2 失效，凭据唯一来源是 infracost auth login OAuth 落盘（CI 场景由官方集成注入访问令牌）。

四、命令行参数详解（实测全景）

4.1 全局 flags（所有子命令共享）

来源：infracost --help 实测回显，默认值照抄：

4.2 scan 专属 flags

来源：infracost scan --help 实测回显：

示例（实测参数解析正常；未登录时输出为登录引导，说明 flags 校验先于业务执行）：

cd /root/demo-terraform
infracost scan --currency EUR --no-color --include-warnings

Please go to the following URL to log in:
https://login.infracost.io/authorize?audience=https%3A%2F%2Fdashboard.api.infracost.io&client_id=uMF6vrdl42thCHGI6Os6UqMqr2Px412O&code_challenge=I0Ni4aEh--8GaBEqVadEIu6tsGO8CibMJCja5tGxw2o&code_challenge_method=S256&icSource=cli&redirect_uri=http%3A%2F%2Flocalhost%3A26372%2Fcallback&response_type=code&scope=offline_access+orgs%3Aread+policies%3Aread+prices%3Aread+runs%3Awrite&state=veN1_upKSK2H89p0cqc3ZQ%3D%3D

Press Enter to open the browser automatically...

4.3 diff 专属 flags

来源：infracost diff --help 实测回显：

官方示例流（--help 示例原文）：

infracost scan --json > infracost-base.json
infracost diff --compare-to infracost-base.json

4.4 inspect 查询参数

infracost inspect 消费最近一次扫描的缓存结果，参数最丰富（完整示例与回显见命令篇）。常用参数速览（实测 --help）：--summary（总览）、--top N（最贵资源）、--top-savings N（最省钱修复点）、--total-savings（年化节省合计）、--missing-tag key（缺失标签）、--invalid-tag key（非法标签值）、--min-cost/--max-cost（成本阈值）、--filter（组合过滤）、--group-by（分组维度）、--fields（列投影）、--addresses-only（仅地址）、--file（读 JSON 文件跳过缓存）、--diagnostics（按项目诊断）。

五、infracost.yml 配置文件详解

infracost.yml 解决的核心问题：一个仓库里有多个 Terraform 项目/环境时，告诉 CLI 每个项目在哪、用哪些变量文件。文件放仓库根，scan 运行时自动发现（官方文档：infracost scan auto-discovers either file when it runs from the repo root）。

5.1 三种配置方式

官方给三种方式（按仓库复杂度选择，来源：Config file 文档 Overview，2026-10-25 实查）：

方式一：auto-detect 定制（自动探测 + 提示词）——大部分场景首选，只写「提示」修正自动探测：

version: 0.1

autodetect:
  env_names:
    - dev
    - qual
    - prod
  exclude_dirs:
    - legacy

方式二：静态配置文件——结构固定的小仓库，逐项目手写：

version: 0.1

projects:
  - path: infra
    name: dev
    terraform_var_files:
      - ../environment/dev.tfvars
  - path: infra
    name: qual
    terraform_var_files:
      - ../environment/qual.tfvars
  - path: infra
    name: prod
    terraform_var_files:
      - ../environment/prod.tfvars

方式三：高级模板（infracost.yml.tmpl）——项目频繁增减的动态 monorepo，模板按目录树展开（Golang text/template 语法）：

version: 0.1

projects:
{{- range $project := matchPaths "environment/:env.tfvars" }}
  {{- if eq $project.env "legacy"}}
  {{- continue }}
  {{- end }}
  - path: .
    name: {{ $project.env }}
    terraform_var_files:
    - {{ $project._path }}
{{- end }}

模板展开后等价于静态配置（environment/ 下每个 <env>.tfvars 生成一个项目，legacy 被排除）；模板文件本身入库，无需提交渲染产物。

5.2 autodetect 块参数表

来源：官方 Config file 文档 Auto-detect parameters 节（2026-10-25 实查）：

5.3 projects 块参数表

来源：官方 Config file 文档 Static config file project parameters 节（2026-10-25 实查）：

5.4 模板语法要点

模板基于 Golang text/template（与 Helm 同源），核心要素（官方文档 Advanced config template syntax 节，2026-10-25 实查）：

• 动作定界符 {{ }}，{{- }} 裁剪空白；支持 if/else if/else、and/or/ne/eq 逻辑；
• range + matchPaths：matchPaths "environment/:env.tfvars" 返回目录树中所有匹配项，逐项展开为项目；:env 是捕获段，以 $project.env 访问，$project._path 为捕获文件的完整路径；
• 全局变量：.RepoName（仓库名）、.Branch（当前分支）、.DetectedRootModules（自动探测的根模块及其 projects）、.DetectedProjects（探测项目的简化视图：Name/Path/TerraformVarFiles/DependencyPaths/Env）。

六、CI/CD 集成配置

6.1 两种集成模式

官方 CI/CD 集成（来源：官网 Integrations 文档，2026-10-25 实查）分两类：

6.2 GitHub App 配置链路（官方 Usage 步骤，实查 2026-10-25）

1. 登录 Infracost Cloud（dashboard.infracost.io，免费试用无需信用卡），每个账号自带个人默认组织；给公司用先在组织下拉中新建组织；
2. Org Settings > Integrations > GitHub 按向导选择要授权的仓库（App 仅需 PR 写权限用于发评论/开修复 PR，其余为只读；官方列有完整权限清单与「Infracost (Limited)」受限版）；
3. 需要定制运行方式时，加 infracost.yml / infracost.yml.tmpl 配置文件（优先级：Org 默认配置 < Repo Settings < 仓库内文件——仓库内文件仅在云端未配置时生效）；
4. 向仓库发一个 PR 即可在 PR 中看到成本差、FinOps 与标签问题；合并后 Infracost Cloud 记录合并时间/审批人/合并人；
5. 门禁：在策略设置开启「Require approval before merging」后，Infracost 会对违规 PR 返回 failed status check；再在 GitHub 侧用 Ruleset（推荐，组织级）或分支保护规则把名为 Infracost（注意大写 I）的 check 设为 Required，即可实现「策略不过不准合并」；
6. PR 评论区可 @infracost help 获取 dismiss/snooze 指引（紧急变更可搁置违规项，Infracost 相应返回 passed 解锁）；
7. 从 GitHub Actions 迁移到 App（官方迁移清单）：装 App → 发测试 PR 验证 → 从工作流中删除原 Infracost steps。

网络放行（GitHub Enterprise Cloud IP 白名单场景，官方实查值）：入站放行 3.133.40.66、3.16.104.91、3.147.121.170、3.141.214.65、18.221.82.195、18.119.42.142（443 端口）；出站放行 dashboard.api.infracost.io:443（按 IP 时为 52.223.24.69、76.223.127.201）。

6.3 自管 CI 集成的配置要点

自管模式在流水线里运行 CLI，配置要点（对应命令均在本机实测其帮助与形态）：

1. 凭据：CI 机器无法交互登录，使用官方 CI 集成的访问令牌注入（GitHub App/云平台生成的 token 走环境变量注入通道；本地交互登录是 infracost auth login，见安装指南十、1）；
2. 步骤：安装 CLI（Docker 镜像 infracost/infracost 或安装脚本）→ 凭据注入 → 仓库根执行 infracost scan（自动发现 infracost.yml/infracost.yml.tmpl，官方文档原文：Infracost scan auto-discovers either file when it runs from the repo root）→ 输出 JSON 供后续步骤消费；
3. 基线 diff：把主干扫描 JSON 存为构建产物，PR 里 infracost diff --compare-to <基线 JSON>；
4. 辅助命令：infracost ci setup（实测：ci 命令族仅含 setup 子命令，用于给当前仓库生成 CI 集成配置）、infracost org current/org switch（多组织流水线切换扫描上下文）。

七、生产配置模板

适用于「单仓多环境 Terraform monorepo、AWS 主力、需纳入云组织统一策略」的典型生产形态（以 8GB 内存通用 CI runner 为基准；Infracost 为一次性执行进程，无驻留内存占用，插件与缓存合计磁盘占用约百 MB 级）：

# /path/to/repo/infracost.yml —— 生产 monorepo 模板
version: 0.1

autodetect:
  # 环境清单：目录树下凡匹配 <路径>/<环境>.tfvars 即生成对应项目
  env_names:
    - dev
    - staging
    - prod
  # 排除历史遗留与实验目录
  exclude_dirs:
    - legacy
    - .terraform
  # 探测深度：目录层级深的 monorepo 适当调大
  max_search_depth: 10
  # 仓库同时存在 terragrunt 与 terraform 时避免类型误判
  # force_project_type: terragrunt

projects:
  # 主基建：同一 path 以不同 var 文件声明三个环境项目
  - path: infra
    name: infra-dev
    terraform_var_files:
      - ../environments/dev.tfvars
  - path: infra
    name: infra-staging
    terraform_var_files:
      - ../environments/staging.tfvars
  - path: infra
    name: infra-prod
    terraform_var_files:
      - ../environments/prod.tfvars
  # 用量敏感项目：挂 usage 文件提升按用量资源（S3/CloudWatch 等）估算精度
  - path: infra
    name: infra-prod-usage
    terraform_var_files:
      - ../environments/prod.tfvars
    usage_file: ../environments/prod-usage.yml
    # GitHub App 用户：只有这些路径变更才触发该项目估算
    dependency_paths:
      - infra/**
      - environments/prod.tfvars

逐项说明：

• env_names + exclude_dirs：修正自动探测——补齐 staging（否则只被识别 dev/prod 的常见问题）并排除 legacy（官方示例同款场景）；
• 三个环境项目显式声明：name 落到 PR 评论里的项目名，评审时一眼分清环境；.auto.tfvars 无需列入 terraform_var_files（自动加载）；
• usage_file：Infracost 的 usage 文件以 YAML 提供月均请求量/存储量等假设值，未提供时按典型默认用量估算（估算口径差异见 A1 篇限制章节）；
• dependency_paths：控制 GitHub App 触发范围，减少无效扫描；设置后 path 自身变更不再触发（官方参数说明原文），故把 infra/** 一并列入；
• 敏感值：env 块可引用 ${MY_ENV_VAR} 形式的既有环境变量传入（如私有 module 的访问令牌），不要把密钥明文写进 infracost.yml。

配置生效验证：

cd /path/to/repo
infracost scan --json | python3 -m json.tool | grep -m 5 '"name"'

（scan --json 输出包含 CLI 实际使用的项目清单，官方文档指定的核对方式；登录后执行。）

八、常见问题（FAQ）

Q1：infracost.yml 放了但没生效？ 三查：文件是否在运行 infracost scan 的工作目录（仓库根）；文件名是 infracost.yml 还是模板 infracost.yml.tmpl（模板按当前目录树展开，展开失败不报错、表现为项目清单为空）；是否被云端 Org/Repo 设置覆盖（云端配置优先，仓库文件只在云端未配置时生效——官方优先级规则）。

Q2：坏 YAML 为什么不报错，直接让我登录？ v2 的凭据校验先于配置解析（本机实测：坏 YAML 下 infracost scan 输出登录引导 URL）。登录后重新执行即可看到 YAML 语法报错；infracost doctor 的 Config file valid 项可作健康信号。

Q3：同一路径多个环境怎么配？ projects 里重复声明同一 path、不同 name 与 terraform_var_files（五、1 方式二即官方示例原样结构）。不要用 env 块传 INFRACOST_ 前缀变量（官方明确其全局作用域，禁止在项目级使用）。

Q4：Terragrunt 和 Terraform 混在一个仓库，探测类型来回跳？ autodetect.force_project_type 强制归类（terraform 或 terragrunt 二选一，官方参数）。

Q5：CI 里没有浏览器，登录怎么办？ CI 不走交互登录：用官方 CI 集成的访问令牌注入（6.2/6.3）；本地无浏览器的开发机用 infracost auth login --oauth-use-device-flow（实测输出 https://login.infracost.io/activate + 设备码）。

Q6：--llm 和 --json 有什么区别？ --json 是完整结构化输出（脚本消费）；--llm 是 token 紧凑格式（LLM 管道/代理消费，代价是丢掉部分冗余字段）。两者均为全局 flags，可叠加 inspect --summary 等查询命令。

Q7：私有 Terraform module 拉取失败？ 配置 --ssh-key-file 指向可访问私有仓库的 SSH 私钥（默认已尝试标准 ~/.ssh 密钥）；CI 场景把私钥落为构建机密钥文件再传入。GitHub App 用户另见官方 Source control integrations 的私有模块章节。

九、参考链接

• Config file 官方参考（本文 5.x 参数表来源）：https://www.infracost.io/docs/config_file
• 官方 Getting Started：https://www.infracost.io/docs/
• GitHub App 集成（本文 6.2 来源）：https://www.infracost.io/docs/integrations/github_app/
• Source control 集成总览：https://www.infracost.io/docs/integrations/source_control/
• Usage-based resources（usage 文件）：https://www.infracost.io/docs/features/usage_based_resources
• Auto-fix PR 博客：https://www.infracost.io/blog/ai-for-finops-fix-cloud-cost-issues-faster/
• CLI 仓库：https://github.com/infracost/cli