如何在 Windows 上修复 Claude Code 中的 pyright-lsp（完整指南）

Source: Dev.to

介绍

如果你在 Windows 上尝试为 Claude Code 启用 pyright LSP 插件时遇到阻碍，本指南将逐一说明在 Windows 上叠加的三个 bug，并提供一个完整、经过测试的解决方案。

启用插件

在 ~/.claude/settings.json 中添加以下内容：

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

或者通过命令面板安装：

/plugin install pyright-lsp@claude-plugins-official

如果出现：

Plugin "pyright-lsp" not found in any marketplace

或之后出现：

ENOENT: no such file or directory, uv_spawn 'pyright-langserver'

请继续下面的步骤。

注册官方 Marketplace（Windows）

在 macOS 上官方 Marketplace 已预先注册；在 Windows 上则没有。向设置中添加 extraKnownMarketplaces 条目：

{
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  },
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

现在命令可以正常工作：

/plugin install pyright-lsp@claude-plugins-official

安装真实的 pyright-langserver 可执行文件

npm 包会生成 pyright-langserver.cmd，这是一个批处理包装器，Claude Code 使用的 libuv 在 Windows 上无法解析。请改用 pip 安装 pyright，它会提供原生的 .exe：

pip install pyright

确认可执行文件已在 PATH 中：

where pyright-langserver

将 Scripts 目录加入 PATH（如有必要）

以 管理员身份 打开 PowerShell 并运行：

$scripts = 'C:\Users\\AppData\Local\Programs\Python\Python311\Scripts'
$current = [System.Environment]::GetEnvironmentVariable('PATH', 'Machine')
[System.Environment]::SetEnvironmentVariable('PATH', $current + ';' + $scripts, 'Machine')

将 “ 替换为你实际的 Windows 用户名。

最终配置

确保你的 ~/.claude/settings.json 同时包含 Marketplace 注册和插件启用：

{
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  },
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

再次运行安装命令（如果尚未执行）：

/plugin install pyright-lsp@claude-plugins-official

彻底关闭 Claude Code，然后重新打开。不要 使用 /reload-plugins；必须完整重启。

打开任意 Python 文件。现在你应该能看到 pyright 诊断自动出现，且 转到定义、查找引用 等功能能够正常工作。

为什么这很重要

启用 LSP 后，Claude Code 能够语义化地导航代码库，而不是仅靠纯文本搜索。它能够理解类型、调用层级和跨文件引用，而无需加载整个文件，这对大型项目来说意义重大。

已知问题

这些 bug 已在官方 issue 跟踪器中记录：

• https://github.com/anthropics/claude-code/issues/32268

预计未来的 Claude Code 版本会在 Windows 上预先注册官方 Marketplace，并为 pyright-langserver 提供合适的 .exe。

测试环境

• Windows 11 Pro
• Claude Code 2.1.71（原生安装）
• Python 3.11