Claude Code 插件更新报错 CWD 路径不匹配 三步手动修复

你用 Claude Code 做多项目管理的时候，大概率遇到过这个场景 —— 在 workspace-A 里装了个自定义插件，切到 workspace-B 想点一下 “Update now” 更新它，结果弹出一行报错：”Plugin ‘X’ is not installed at scope project (/path/to/workspace-B)”。你明明装了这个插件，它也出现在插件列表里，就是不能更新 —— 今天这个 Bug（Issue #45505）告诉你问题出在哪，以及怎么用 3 步绕过它。

Claude Code 插件更新的 CWD 校验逻辑到底卡在哪

Claude Code v2.1.96 的项目作用域插件在安装时会把当前工作目录（CWD）写入 installed_plugins.json 的 projectPath 字段，而后续的 Update now 操作会严格校验当前 CWD 是否与该字段一致。

问题根因在于 installed_plugins.json 中的 projectPath 被硬编码为安装时刻的绝对路径，而不是相对于市场源目录（marketplace）的可解析路径。

// ~/.claude/plugins/installed_plugins.json（问题结构）"my-plugin@my-marketplace": [{  "scope": "project",  "projectPath": "/path/to/workspace-A",  // ← 硬编码！切换工作区就失效  "version": "0.1.0",  "enabled": true}]

CWD 校验本身不是多余设计，它的初衷是防止不同工作区的同名插件互相干扰，但在多工作区共享同一个本地市场源时，这个安全检查反而成了障碍。CWD 校验是 Claude Code 插件系统的一种路径安全验证机制，确保插件只在其所属的项目目录中运行。

好消息是这个问题不需要等官方修复 ——projectPath 就是一个普通的 JSON 字段，改一行就能让 Update now 恢复正常。

报错不可怕，可怕的是你以为是自己操作错了，其实只是工具把一个该用相对路径的地方写死了绝对路径 —— 这类路径绑定 Bug 在 CLI 工具里比你想象的多得多。

但修改之前你需要知道一个细节 —— 改错了可能导致插件列表异常。

三步手动修复 projectPath 跳过等待官方修复

修复的第一步永远是备份原始文件 ——installed_plugins.json 记录了你所有已安装插件的配置状态，误操作会导致插件列表丢失或混乱。

# Step 1: 备份原始配置cp ~/.claude/plugins/installed_plugins.json \   ~/.claude/plugins/installed_plugins.json.bak# Step 2: 定位目标插件条目cat ~/.claude/plugins/installed_plugins.json | grep -A5 "my-plugin"

用任意文本编辑器打开 installed_plugins.json，找到你那个 CC 插件的 projectPath 字段，将它的值从安装时的旧路径改为你想执行更新的工作区目录的绝对路径。

// 修改前（❌ 更新时会报CWD不匹配）"projectPath": "/Users/yourname/project-A"// 修改后（✅ 在project-B中执行Update now不再报错）"projectPath": "/Users/yourname/project-B"

保存文件后回到 Claude Code 界面，再次点击 Plugins > [插件名] > Update now—— 这次不会再弹出 scope 不匹配的错误，插件会正常拉取最新版本并完成更新。

修改时有三个坑需要注意：

1. scope 字段
   
   ：禁止修改（否则插件作用域会乱）
2. JSON 格式
   
   ：注意 trailing comma（会导致解析失败）
3. 热加载
   
   ：无需重启 Claude Code（配置是热加载的）

# 快速验证JSON合法性python3 -c "import json; json.load(open('$HOME/.claude/plugins/installed_plugins.json'))"echo "✅ JSON格式正确"

// 将scope从"project"改为"user"（彻底绕过CWD校验）"my-plugin@my-marketplace": [{  "scope": "user",          // ← 改这里  "projectPath": null,      // user scope不需要  "version": "0.1.0",  "enabled": true}]

大多数 CLI 工具的配置 Bug 都能通过 “找到它存状态的 JSON/XML 文件→改那个字段” 解决 —— 关键是你得知道它把状态存在哪，以及每个字段到底管什么。

官方可能在未来版本修复此问题，但你至少应该知道…

为什么 Claude Code 要做这个 CWD 校验 设计思路解读

Claude Code 的插件系统采用 scope 机制来隔离不同级别的插件：global（内置）、user（用户级）、project（项目级），其中 project scope 通过 projectPath 实现 “这个插件只属于某个项目” 的强绑定。

project scope 的设计目标是让同一个插件在不同的工作区拥有独立的配置和版本 —— 比如项目 A 需要插件的 v1.0 稳定版，项目 B 想测试 v2.0 beta 版，projectPath 保证了它们互不干扰。

问题出在一个隐含假设上：系统默认安装插件的 CWD 就是你以后永远在这个目录里用它 —— 但对于使用本地市场源（local marketplace）的开发者来说，marketplace 本身才是 “固定锚点”，而不是某个具体的 workspace 目录。

// .claude-plugin/marketplace.json（本地市场源定义）{  "source": "./claude-plugin",  "plugins": ["my-plugin"]}// 问题：安装时CWD = /project-A// 但marketplace实际位于 = /shared-marketplace  // projectPath记错了"家"

好的工具设计会在 “安全性” 和 “便利性” 之间做取舍 ——CWD 校验保护了 99% 的单工作区用户，但也确实挡住了那 1% 用本地市场源做多项目管理的开发者。

Issue #45505 的作者提出了三个修复方向：

1. marketplace 目录替代 CWD
   
   作为 projectPath（推荐，最干净利落）
2. 白名单启用插件的工作区
3. 对 user scope 放行更新权限

除了等官方修复，你在日常使用中还可以做一件事来减少遇到这个问题的概率 ——

多项目管理预防 插件安装时的 CWD 意识

预防这个问题的最简单方法是：每次安装项目作用域插件之前，先用 pwd 确认当前目录是你希望 “绑定” 的工作区 —— 因为 Claude Code 会在安装那一刻把 pwd 的结果写死到 projectPath 里。

# 安装前的安全习惯cd /path/to/correct-workspace   # ① 先到正确目录pwd                              # ② 确认路径claude                            # ③ 启动Claude Code# 然后在插件面板安装 → projectPath自动指向这里

问自己一个问题：这个插件是不是所有项目都要用？如果是，直接装成 user scope—— 省去后面所有 projectPath 相关的麻烦，Update now 在任何目录都能正常工作。

• 仅单个项目用
  
   → project scope ✅
• 多个项目共用
  
   → user scope ✅（推荐）
• 团队共享
  
   → global/marketplace ✅

installed_plugins.json 会随着你的插件安装 / 卸载操作逐渐膨胀 —— 已经删除的项目残留条目、重复安装的同名插件、版本号混乱等问题都会积累，建议每个月做一次 clean-up。

# 一键查看当前所有已安装插件的scope分布cat ~/.claude/plugins/installed_plugins.json | \  python3 -c "import json,sysdata=json.load(sys.stdin)for k,v in data.items():    for item in v:        print(f'{item.get(\"scope\",\"?\"):8} | {k}')"

Claude Code 的插件系统还在快速迭代中，这种边界情况的 Bug 不可避免 —— 但作为使用者，了解它的配置文件结构和 scope 机制，能让你在遇到问题时从 “到处搜报错信息” 变成 “直接去改配置”。

如果你也遇到过 Claude Code 插件的 scope/path 类报错，点个在看 —— 你的同事可能正在同一个报错面前抓耳挠腮，而这篇文章刚好能帮他省掉半小时排错时间。

Claude Code 的插件系统在 v2.1.96 版本还存在一些边缘场景的处理不够完善 ——CWD 与 projectPath 的强绑定就是其中一个。但了解了它的配置机制后，这类问题从 “无法理解的报错” 变成了 “改一行 JSON 就好” 的小事。更重要的是，这种 “找配置文件→理解字段含义→精准修改” 的排查思路，适用于几乎所有基于 JSON/YAML 配置的 CLI 工具。