教程

Claude Code 插件配置迁移指南：pluginConfigs 项目级设置失效应对方案

Claude Code v2.1.207 起，插件配置值 pluginConfigs 不再读取项目级 .claude/settings.json。本文详细讲解这项变化的背景、受影响场景，并提供从项目级迁移到用户级/企业管理设置/CI 参数的完整操作步骤和检查清单。

2026/7/114分钟 阅读ClaudeEagle

Claude Code v2.1.207（2026-07-11）修改了插件配置值（pluginConfigs）的读取规则——项目级的 .claude/settings.json 不再被读取。如果你的团队依赖项目级配置给插件传参，升级后插件可能会因为读不到配置而行为异常。本文提供迁移方案。

变化说明

官方原文：

Plugin option values (pluginConfigs) are no longer read from project-level .claude/settings.json; only user, --settings, and managed settings are honored.

升级前后的读取优先级对比：

升级前，pluginConfigs 读取来源包括： ✓ 项目级 .claude/settings.json ✓ 用户级 ~/.claude/settings.json ✓ --settings 命令行参数 ✓ 企业管理设置（managed settings） 升级后（v2.1.207+），pluginConfigs 读取来源仅包括： ✗ 项目级 .claude/settings.json（已移除） ✓ 用户级 ~/.claude/settings.json ✓ --settings 命令行参数 ✓ 企业管理设置（managed settings）

为什么会有这个改动

这项收紧与同版本修复的插件 Shell 注入漏洞是同一条安全主线的两个层面（详见站内深度文章《v2.1.207 安全深度解析》）。核心逻辑是：项目级配置文件可以随代码仓库一起被提交和分发，这意味着一个恶意仓库理论上可以在.claude/settings.json 中夹带精心构造的插件配置值，在开发者克隆并打开该仓库时悄悄生效——属于典型的供应链攻击面。

把 pluginConfigs 的读取来源限制在用户级和企业管理级，意味着插件的行为参数不能再被仓库本身悄悄控制，只能由使用者本人或组织管理员显式配置，从根源上切断了这条攻击路径。

受影响的场景

如果你符合以下任一情况，升级到 v2.1.207 后需要重新检查配置：

  • 团队约定把插件的 API Key、开关选项等配置写在项目仓库内的 .claude/settings.json，方便团队成员克隆仓库后开箱即用
  • 使用了依赖 pluginConfigs 读取项目级配置来实现「不同项目使用不同插件参数」的插件
  • CI/CD 流水线中依赖项目级配置文件传递插件参数

迁移步骤

第一步：找出现有的项目级插件配置

bash
# 检查项目根目录的配置文件
cat .claude/settings.json | grep -A 20 pluginConfigs

第二步：迁移到用户级设置

bash
# 编辑用户级设置文件
vi ~/.claude/settings.json
json
// ~/.claude/settings.json
{
  "pluginConfigs": {
    "your-plugin-name": {
      "apiKey": "...",
      "someOption": true
    }
  }
}

注意：迁移到用户级后，配置不再随仓库一起分发，团队每个成员需要各自在本地配置一次。这是安全性提升带来的必然代价——团队协作的便利性有所下降，但换来的是插件参数不会被仓库内容悄悄控制。

第三步：需要团队统一配置的场景，改用企业管理设置

如果团队规模较大，希望所有成员自动获得统一的插件配置（而不是每人手动配置一次），应该改用企业管理设置（managed settings），这类配置由组织管理员统一下发，不受这次收紧影响：

bash
# 企业管理设置通常通过 MDM 或统一部署工具下发
# 具体路径和机制参考企业管理文档

第四步：CI/CD 场景改用 --settings 参数

bash
# CI 流水线中显式传入配置文件路径
claude -p "执行代码审查" --settings ci-plugin-settings.json

--settings 命令行参数不受本次收紧影响，适合 CI/CD 这类非交互式场景显式指定配置。

迁移检查清单

  • 检查所有项目的 .claude/settings.json 中是否存在 pluginConfigs 字段
  • 将需要个人使用的配置迁移到 ~/.claude/settings.json
  • 将需要团队统一下发的配置迁移到企业管理设置
  • 将 CI/CD 中依赖的配置改为 --settings 参数显式传入
  • 升级后运行 claude /doctor 确认插件配置读取正常
  • 通知团队成员各自完成用户级配置迁移（如适用）

总结

这次配置读取来源的收紧，本质上是用「团队协作便利性」换「供应链安全性」——对多数正常使用插件的团队而言，只是需要多做一次一次性迁移；但对于原本就可能被恶意仓库利用的攻击面，这是一次有效的封堵。建议尽快按上述清单完成迁移，避免升级后插件因读不到配置而静默失效。

来源：Claude Code Changelog v2.1.207 — Anthropic，2026-07-11