首页
/ Zed 编辑器 PHP 开发环境配置完全指南：语言服务器、PHPDoc 高亮与 Xdebug 调试

Zed 编辑器 PHP 开发环境配置完全指南：语言服务器、PHPDoc 高亮与 Xdebug 调试

2026-09-06 19:04:03作者：滕妙奇
zed
Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
项目地址：https://gitcode.com/GitHub_Trending/ze/zed

Zed 的 PHP 支持由官方 PHP 扩展提供，依托 Tree-sitter 完成语法高亮、依托 Language Server Protocol（LSP）提供补全与诊断、并内置 Xdebug 调试适配器。本文从零讲解如何在 Zed 中安装 PHP 运行时与扩展、在 Phpactor / Intelephense / PHP Tools / PHPantom 之间选择并切换默认语言服务器、正确配置各服务器的授权（license）与初始化参数，以及如何借助 Tailwind CSS 语言服务器在 PHP 与 Blade 模板中获得样式类补全。读完本文，你将能根据项目需求为 PHP 工作流搭建一套可复现的 Zed 配置。

PHP 支持在 Zed 中的定位与架构

在 语言支持总览 中，PHP 未标注“内置（*）”，意味着它不像 Rust、Python 那样随 Zed 核心出厂，而是通过扩展方式获得支持——用户需自行安装 PHP 扩展。

整个 PHP 语言能力栈由三部分组成：

  • Tree-sitter 语法解析：语法高亮、折叠、大纲等结构化能力由 tree-sitter/tree-sitter-php 提供；
  • LSP 语言服务器：代码补全、跳转、诊断、重构等语义能力默认交给 Phpactor（备选 Intelephense、PHP Tools、PHPantom）；
  • 调试适配器（DAP）：通过 Xdebug 提供断点、单步、变量检查能力。

其中 PHP 调试适配器属于“无需额外搭建即可用”的一类。在 调试器文档 的语言列表中，PHP 被标注为 (built-in)：Zed 自身实现了 Debug Adapter Protocol (DAP) 客户端，因此只要在 Zed 中完成断点与 launch 配置即可接入 Xdebug，无需再安装第三方调试插件。

说明：语法树与各语言服务器实现细节属于 PHP 扩展仓库（zed-extensions/php）与上游项目范畴；本文聚焦于在 Zed 中的配置层操作。

安装 PHP 运行时

PHP 扩展要求机器上已安装 PHP，且 php 可执行文件能被 Zed 在 PATH 中找到。按平台执行安装：

# macOS via Homebrew
brew install php

# Debian/Ubuntu
sudo apt-get install php-cli

# CentOS 8+/RHEL
sudo dnf install php-cli

# Arch Linux
sudo pacman -S php

# 检查 PHP 路径
## macOS 和 Linux
which php

## Windows
where php

安装后务必确认 which php（Windows 用 where php）有输出；若输出为空，说明 php 不在 PATH 中，语言服务器将无法解析与诊断 PHP 代码。

选择语言服务器：默认与切换机制

PHP 扩展默认使用 Phpactor。Zed 的语言服务器选择机制在 configuring-languages.md 中有系统说明：language_servers 是一个有序列表，被列出的服务器保持相对顺序，未列出的其余已注册服务器由 "..." 通配符在列表中该位置展开，带 ! 前缀的条目被整体排除。

注意一个关键语义：当你在设置中覆盖 language_servers 时，这份列表是完全替换默认列表，而不是追加合并。因此若想去掉某服务器，必须显式写出 "!serverName"。

通用的替换示例如下：

{
  "languages": {
    "PHP": {
      "language_servers": [
        "intelephense",
        "!phpactor",
        "!phptools",
        "!phpantom",
        "..."
      ]
    }
  }
}

即在“主服务器为 Intelephense、其余按需展开、同时停用另外三个”之间做显式声明。下面的小节分别给出以每个服务器为主力的完整配置模板。

配置的落点有两个（任选其一）：

  • 图形界面：Zed: Open Settings 打开设置面板，在 Languages > PHP 下编辑；
  • 配置文件：用户级 ~/.config/zed/settings.json，或项目级 .zed/settings.json。

Intelephense

Intelephense 是采用 freemium 商业模式的专有语言服务器：基础功能免费，部分特性需要购买 premium 许可证解锁。

{
  "languages": {
    "PHP": {
      "language_servers": [
        "intelephense",
        "!phpactor",
        "!phptools",
        "!phpantom",
        "..."
      ]
    }
  }
}

许可证的两种提供方式

方式一：把许可证文件放到家目录固定位置，Zed 启动服务器时自动读取：

  • macOS / Linux：~/intelephense/licence.txt
  • Windows：%USERPROFILE%/intelephense/licence.txt

方式二：通过 LSP 初始化选项显式传入许可证内容本身，或传入包含许可证的文件路径。例如把许可证文件路径作为初始化选项：

{
  "lsp": {
    "intelephense": {
      "initialization_options": {
        "licenceKey": "/path/to/licence.txt"
      }
    }
  }
}

关于“文件路径还是文件内容”，以你实际获得的许可证形态为准：若手里是许可证文本，也可将 licenceKey 的值直接替换为文本内容。initialization_options 只在服务器启动时发送一次，因此修改后需要重启语言服务器（或重载窗口）才会生效。

PHP Tools

PHP Tools（devsense 出品）同样是专有语言服务器，提供免费与付费两层特性，激活 premium 需要购买许可证。将 PHP Tools 设为主服务器：

{
  "languages": {
    "PHP": {
      "language_servers": [
        "phptools",
        "!intelephense",
        "!phpactor",
        "!phpantom",
        "..."
      ]
    }
  }
}

授权方式一：初始化选项注入许可证

注意这里 initialization_options 内部使用的是字符串键 "0"，值与普通嵌套对象不同：

{
  "lsp": {
    "phptools": {
      "initialization_options": {
        "0": "your_license_key"
      }
    }
  }
}

授权方式二：项目级环境变量

将许可证写入项目根目录的 .env 文件，通过环境变量 DEVSENSE_PHP_LS_LICENSE 传给服务器：

DEVSENSE_PHP_LS_LICENSE="your_license_key"

两种方式二选一即可，均用于让服务器识别 premium 授权。

Phpactor

Phpactor 是 PHP 扩展的默认语言服务器，也是该语言默认配置中处于“开启”状态的服务器。若此前切换过其他服务器，可通过如下配置将控制权交还给 Phpactor：

{
  "languages": {
    "PHP": {
      "language_servers": [
        "phpactor",
        "!intelephense",
        "!phptools",
        "!phpantom",
        "..."
      ]
    }
  }
}

PHPantom

PHPantom 作为另一可选实现同样支持通过 language_servers 启停。将其设为主服务器：

{
  "languages": {
    "PHP": {
      "language_servers": [
        "phpantom",
        "!phpactor",
        "!intelephense",
        "!phptools",
        "..."
      ]
    }
  }
}

四个服务器的对照速查

服务器 授权模型 关键配置入口
Phpactor 开源（默认） languages.PHP.language_servers 中列出 phpactor
Intelephense 专有，freemium ~/intelephense/licence.txt 或 lsp.intelephense.initialization_options.licenceKey
PHP Tools 专有，需购买 premium lsp.phptools.initialization_options["0"] 或 DEVSENSE_PHP_LS_LICENSE 环境变量
PHPantom 备选实现 languages.PHP.language_servers 中列出 phpantom

PHPDoc：文档注释的语法高亮

除 PHP 源码本身的 Tree-sitter 语法（tree-sitter-php）之外，Zed 还支持 PHPDoc 注释的语法高亮，解析由 claytonrcarter/tree-sitter-phpdoc 提供。这意味着 /** @var Foo */、@param、@return 等标签在注释内会被单独着色，无需任何额外配置即可生效——该能力随 PHP 扩展一并打包。

使用 Xdebug 调试 PHP

PHP 扩展通过 Xdebug 提供调试能力。调试依赖 Zed 内置的 DAP 客户端，因此你只需要告诉 Zed 启动哪个调试会话。项目调试配置放在项目根目录的 .zed/debug.json（数组格式），Zed 也会读取 .vscode/launch.json 作为备选来源；如果想跨项目复用，可通过 Zed: Open Debug Tasks 打开并编辑全局 debug.json（macOS 为 ~/Library/Application Support/Zed/debug.json，Linux 为 ~/.config/zed/debug.json）。

一个典型的 .zed/debug.json 包含“监听 Xdebug 连接”与“调试当前测试”两种场景：

[
  {
    "label": "PHP: Listen to Xdebug",
    "adapter": "Xdebug",
    "request": "launch",
    "port": 9003
  },
  {
    "label": "PHP: Debug this test",
    "adapter": "Xdebug",
    "request": "launch",
    "program": "vendor/bin/phpunit",
    "args": ["--filter", "$ZED_SYMBOL"]
  }
]

各字段含义：

  • label：显示在调试任务选择器中的名称；
  • adapter：固定为 Xdebug（对应内置适配器，无需额外安装）；
  • request：均为 launch 型配置；
  • port：Xdebug 监听端口。9003 是 Xdebug 3 的默认调试端口，若你的 xdebug.client_port 不同，这里必须同步修改；
  • program + args：用于“调试单个测试”的场景，$ZED_SYMBOL 会被替换为光标处符号（通常是测试方法名），从而让 phpunit --filter <方法名> 只运行当前测试并可在其中下断点。

常见排障清单

若断点不命中或连接失败，按顺序排查：

  • 确认 Xdebug 已按当前 PHP 版本正确安装（php -m | grep xdebug 可快速验证）；
  • 确认 Xdebug 以 debug 模式运行（xdebug.mode=debug）；
  • 确认 Xdebug 真的发起了调试会话（例如 xdebug.start_with_request=yes、CLI 时使用 XDEBUG_SESSION=1 环境变量、或使用浏览器扩展触发）；
  • 确认 Xdebug 与 Zed 之间的 host 与 port 完全一致（两边默认都在本机 9003 端口握手）；
  • 在被调试页面中调用 xdebug_info()，直接查看诊断日志中 Xdebug 的实际模式、端口与握手状态，这是定位问题最快的手段。

在 PHP / Blade 中启用 Tailwind CSS 补全

Tailwind CSS 语言服务器默认只在 HTML、CSS、JS/TS 等原生语言文件里提供类名补全。要让它在 PHP 文件内嵌的 HTML 属性中也生效，需要告诉服务器“把 PHP 当作 HTML 处理”，并提供从 HTML 属性中提取 class 的正则。

值得说明的是，Zed 核心代码对 Tailwind 适配器的注册是跨语言的。在 crates/languages/src/lib.rs 中，tailwindcss-language-server 作为可用 LSP 适配器被注册给了包括 PHP 在内的一批语言；同时其 language_ids 映射在 crates/languages/src/tailwind.rs 中把 PHP 对应为 php。也就是说适配器本身对 PHP 已默认可用，但服务器默认的 includeLanguages 只覆盖 html/css/js/ts 等（见 tailwind.rs 中对默认值的填充逻辑），并不会自动补全 PHP 内的 class——这正是下面需要手工配置 includeLanguages 与 classRegex 的原因。

将以下内容写入 settings.json：

{
  "lsp": {
    "tailwindcss-language-server": {
      "settings": {
        "includeLanguages": {
          "php": "html"
        },
        "experimental": {
          "classRegex": [
            "class=\"([^\"]*)\"",
            "class='([^']*)'",
            "class=\\\"([^\\\"]*)\\\""
          ]
        }
      }
    }
  }
}

配置生效后，在 PHP 文件内嵌的 HTML 中即可实时获得 Tailwind 类名补全：

<?php
// PHP file with HTML:
?>
<div class="flex items-center <completion here>">
  <p class="text-lg font-bold <completion here>">Hello World</p>
</div>

补充说明：lsp.<server>.settings 走的是 LSP 的 workspace/configuration 通道，服务器可多次查询、改动即时生效，这有别于只在启动时下发一次的 initialization_options（详见 configuring-languages.md）。嵌套对象应写成对象层级而非 点分字符串，上面的写法即为标准范式。

Laravel / Blade 的额外配置

Blade 模板以 @class([...]) 指令传递类名，且 {{ }} 中会混入 PHP 表达式，因此需要追加两条规则：把 blade 也声明为 html，并增加一条针对 @class([...]) 的正则：

{
  "lsp": {
    "tailwindcss-language-server": {
      "settings": {
        "includeLanguages": {
          "php": "html",
          "blade": "html"
        },
        "experimental": {
          "classRegex": [
            "class=\"([^\"]*)\"",
            "class='([^']*)'",
            "class=\\\"([^\\\"]*)\\\"",
            "@class\\(\\[([^\\]]*)\\]\\)"
          ]
        }
      }
    }
  }
}

之后在 Blade 的 HTML 属性与 @class() 指令内都能获得补全：

{{-- Blade file --}}
<div class="flex {{ $customClass }} <completion here>">
  @class(['flex', 'items-center', '<completion here>'])
</div>

小结与推荐实践

针对不同项目形态，可直接套用下列组合：

  • 追求开箱即用：保持默认 Phpactor，仅安装 PHP 扩展即可获得补全、诊断与跳转；
  • 团队统一、需要商业支持：切换 Intelephense 或 PHP Tools，并按上文方式注入许可证，注意 language_servers 列表为整体替换语义，务必同时声明 "!..." 排除项；
  • Laravel/Tailwind 项目：额外配置 tailwindcss-language-server 的 includeLanguages 与 classRegex（含 Blade 变体），让样式类补全贯通 PHP 与模板；
  • 需要单测与断点联调：将 PHP: Listen to Xdebug 与 PHP: Debug this test 两段配置写入项目 .zed/debug.json，并确保 Xdebug 以 debug 模式监听 9003 端口。

所有配置均可在用户级 settings.json 与项目级 .zed/settings.json 之间按需分发，前者适合个人偏好，后者适合随仓库共享给协作者。

zed
Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
项目地址：https://gitcode.com/GitHub_Trending/ze/zed
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
855
1.34 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
589
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.73 K
docsdocs
暂无描述
Markdown
897
5.79 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.56 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
998
511
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
909
1.83 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313