如何在 Zed 中设置 Python

Zed 原生支持 Python。

在 Zed 中打开您的第一个 Python 项目

安装 Zed 和 Python 后，打开包含 Python 代码的文件夹即可开始工作。

第一步：使用 Python 项目启动 Zed

打开 Zed。从菜单栏中选择“文件”>“打开文件夹”，或从终端启动

zed path/to/your/project

Zed 将使用其原生的 tree-sitter-python 解析器自动识别 .py 文件，无需插件或手动设置。

第二步：使用集成终端（可选）

Zed 包含一个集成终端，可从底部面板访问。如果 Zed 检测到您的项目正在使用虚拟环境，它将在新创建的终端中自动激活。您可以使用 detect_venv 设置配置此行为。

在 Zed 中配置 Python 语言服务器

Zed 开箱即用地提供了多个 Python 语言服务器。默认情况下，basedpyright 是主要的语言服务器，Ruff 用于格式化和 linting。

其他内置语言服务器是

Ty——来自 Astral 的新兴语言服务器，以速度著称。
Pyright——basedpyright 的基础。
PyLSP——一个基于插件的语言服务器，集成了 pycodestyle、autopep8 和 yapf 等工具。

这些默认禁用，但可以在您的设置中启用。例如：

{
  "languages": {
    "Python": {
      "language_servers": [
        // Disable basedpyright and enable Ty, and otherwise
        // use the default configuration.
        "ty",
        "!basedpyright",
        "..."
      ]
    }
  }
}

请参阅：使用语言服务器，了解如何启用和禁用语言服务器的更多信息。

Basedpyright

basedpyright 是 Zed v0.204.0 及更高版本中主要的 Python 语言服务器。它提供核心语言服务器功能，如导航（跳转到定义/查找所有引用）和类型检查。与 Pyright 相比，它增加了对其他语言服务器功能（如内联提示）和检查规则的支持。

请注意，虽然 basedpyright 在隔离状态下默认为 recommended 类型检查模式，但 Zed 默认将其配置为使用限制较少的 standard 模式，这与 Pyright 的行为一致。您可以使用 pyrightconfig.json 或 pyproject.toml 中的 typeCheckingMode 设置为您的项目设置类型检查模式，这将覆盖 Zed 的默认设置。请继续阅读以获取有关如何配置 basedpyright 的更多详细信息。

Basedpyright 配置

basedpyright 从两种不同类型的源读取配置选项

语言服务器设置（“工作区配置”），必须在每个编辑器中配置（在 Zed 的情况下使用 settings.json），但适用于在该编辑器中打开的所有项目
配置文件（pyrightconfig.json、pyproject.toml），它们是独立于编辑器的，但特定于它们所在的此项目

根据经验法则，只有在使用编辑器中的 basedpyright 时才相关的选项必须在语言服务器设置中设置，即使您作为命令行工具运行它也相关的选项必须在配置文件中设置。与内联提示相关的设置是第一类示例，而诊断类别设置是第二类示例。

下面提供了两种配置的示例。有关可用选项的全面列表，请参阅 basedpyright 文档中关于语言服务器设置和配置文件的信息。

语言服务器设置

Zed 中 basedpyright 的语言服务器设置可以在 settings.json 的 lsp 部分中设置。

例如，为了

诊断工作区中的所有文件，而不是默认的仅打开文件
禁用函数参数上的内联提示

您可以使用以下配置

{
  "lsp": {
    "basedpyright": {
      "settings": {
        "analysis": {
          "diagnosticMode": "workspace",
          "inlayHints.callArgumentNames": false
        }
      }
    }
  }
}

配置文件

basedpyright 从 pyrightconfig.json 配置文件以及 pyproject.toml 清单的 [tool.basedpyright] 和 [tool.pyright] 部分读取项目特定配置。如果配置同时存在于这两个位置，pyrightconfig.json 将覆盖 pyproject.toml。

这是一个 pyrightconfig.json 文件的示例，它将 basedpyright 配置为使用 strict 类型检查模式，并且不为 __pycache__ 目录中的任何文件发出诊断信息

{
  "typeCheckingMode": "strict",
  "ignore": ["**/__pycache__"]
}

PyLSP

python-lsp-server，通常称为 PyLSP，默认集成了许多外部工具（autopep8、mccabe、pycodestyle、yapf），而其他工具是可选的，必须明确启用和配置（flake8、pylint）。

有关更多信息，请参阅Python 语言服务器配置。

虚拟环境

虚拟环境是一种有用的工具，用于为特定项目固定 Python 版本和一组依赖项，使其与同一机器上的其他项目隔离。Zed 内置支持基于与语言无关的工具链概念发现、配置和激活虚拟环境。

请注意，如果您的全局 Python 安装，它在 Zed 的用途中也被视为一个工具链。

创建虚拟环境

如果您的项目尚未设置虚拟环境，您可以按如下方式创建一个

python3 -m venv .venv

或者，如果您正在使用 uv，第一次运行 uv sync 将创建一个虚拟环境。

Zed 如何使用 Python 工具链

Zed 以以下方式使用为您的项目选择的 Python 工具链

内置语言服务器将自动配置工具链的 Python 解释器路径，如果适用，还会配置虚拟环境。这对于它们解析依赖项很重要。（请注意，扩展提供的语言服务器目前无法这样自动配置。）
Python 任务（例如 pytest 测试）将使用工具链的 Python 解释器运行。
如果工具链是虚拟环境，当您在 Zed 的集成终端中启动新 shell 时，环境的激活脚本将自动运行，让您方便地访问所选的 Python 解释器和依赖集。
如果在活动的虚拟环境中安装了内置语言服务器，则将使用该二进制文件，而不是 Zed 自动安装的私有二进制文件。这也适用于 debugpy。

选择工具链

对于大多数项目，Zed 将自动选择正确的 Python 工具链。在具有多个虚拟环境的复杂项目中，可能需要覆盖此选择。您可以使用工具链选择器从 Zed 发现的列表中选择一个工具链，如果列表中没有，也可以手动指定工具链的路径。

代码格式化和 Linting

Zed 为 Python 代码提供 Ruff 格式化程序和 linter。（具体来说，Zed 使用 ruff server 子命令将 Ruff 作为 LSP 服务器运行。）格式化和 linting 默认启用，包括保存时格式化。

配置格式化

您可以在 settings.json 中禁用 Python 文件的保存时格式化

{
  "languages": {
    "Python": {
      "format_on_save": "off"
    }
  }
}

或者，您可以使用 black 命令行工具进行 Python 格式化，同时保持 Ruff 启用用于 linting

{
  "languages": {
    "Python": {
      "formatter": {
        "external": {
          "command": "black",
          "arguments": ["--stdin-filename", "{buffer_path}", "-"]
        }
      }
      // Or use `"formatter": null` to disable formatting entirely.
    }
  }
}

配置 Ruff

与 basedpyright 类似，Ruff 在 Zed 中使用时会从 Zed 的语言服务器设置和配置文件（ruff.toml）中读取选项。与 basedpyright 不同，所有选项都可以在这些位置中的任何一个中配置，因此选择将 Ruff 配置放在何处取决于您是希望它在项目之间共享但特定于 Zed（在这种情况下您应该使用语言服务器设置），还是特定于一个项目但适用于所有 Ruff 调用（在这种情况下您应该使用 ruff.toml）。

这是一个在 Zed 的 settings.json 中使用语言服务器设置来禁用 Zed 中所有 Ruff lint 的示例（同时仍将 Ruff 用作格式化程序）

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "exclude": ["*"]
        }
      }
    }
  }
}

这是一个带有 linting 和格式化选项的 ruff.toml 示例，改编自 Ruff 文档

[lint]
# Avoid enforcing line-length violations (`E501`)
ignore = ["E501"]

[format]
# Use single quotes when formatting.
quote-style = "single"

有关更多详细信息，请参阅 Ruff 文档中关于配置文件和语言服务器设置的信息，以及选项列表。

调试

Zed 通过 debugpy 适配器支持 Python 调试。您可以不进行配置就直接开始，或者在 .zed/debug.json 中定义自定义启动配置文件。

无需设置即可开始调试

Zed 可以自动检测可调试的 Python 入口点。按 F4（或从命令面板运行 debugger: start）以查看当前项目的可用选项。这适用于

Python 脚本
模块
pytest 测试

Zed 在底层使用 debugpy，但无需手动适配器配置。

定义自定义调试配置

对于可重用设置，请在项目根目录中创建一个 .zed/debug.json 文件。这使您能够更好地控制 Zed 如何运行和调试您的代码。

debugpy 配置文档

调试活动文件

[
  {
    "label": "Python Active File",
    "adapter": "Debugpy",
    "program": "$ZED_FILE",
    "request": "launch"
  }
]

这将运行编辑器中当前打开的文件。

调试 Flask 应用

对于使用 Flask 的项目，您可以定义完整的启动配置

.venv/
app/
  init.py
  main.py
  routes.py
templates/
  index.html
static/
  style.css
requirements.txt

…可以使用以下配置

[
  {
    "label": "Python: Flask",
    "adapter": "Debugpy",
    "request": "launch",
    "module": "app",
    "cwd": "$ZED_WORKTREE_ROOT",
    "env": {
      "FLASK_APP": "app",
      "FLASK_DEBUG": "1"
    },
    "args": [
      "run",
      "--reload", // Enables Flask reloader that watches for file changes
      "--debugger" // Enables Flask debugger
    ],
    "autoReload": {
      "enable": true
    },
    "jinja": true,
    "justMyCode": true
  }
]

这些可以组合起来为 Web 服务器、测试运行器或自定义脚本定制体验。

故障排除并保持高效的 Python 设置

Zed 旨在最大限度地减少配置开销，但偶尔仍会出现问题——尤其是在环境、语言服务器或工具方面。以下是让您的 Python 设置顺利运行的方法。

解决语言服务器启动问题

如果语言服务器没有响应，或者诊断或自动完成等功能不可用

检查您的 Zed 日志（使用 zed: open log 操作）中与您尝试使用的语言服务器相关的错误。如果语言服务器根本未能启动，您很可能会在这里找到有用的信息。
使用语言服务器日志视图了解受影响语言服务器的生命周期。您可以使用 dev: open language server logs 操作访问此视图，或单击状态栏中的闪电图标并选择您的语言服务器。此视图中最有用的数据是
- “服务器日志”，显示语言服务器打印的任何错误
- “服务器信息”，显示有关语言服务器如何启动的详细信息
验证您的 settings.json 或 pyrightconfig.json 语法是否正确。
重新启动 Zed 以重新初始化语言服务器连接，或者尝试使用 editor: restart language server 重新启动语言服务器

如果语言服务器无法解析导入，并且您正在使用虚拟环境，请确保在选择器中选择了正确的环境。您可以使用“服务器信息”视图确认 Zed 正在向语言服务器发送哪个虚拟环境——查找末尾的 * Configuration 部分。