VS Code 不能运行 PHP WebSocket 服务，需用 php 命令行启动；必须选用 ratchet 或 reactphp 等支持 WebSocket 协议的库，禁用 php -S；确保 sockets 扩展启用、端口未被占用、前端 URL 与后端监听地址严格一致（如 ws://127.0.0.1:8080）。
VS Code 本身不运行 PHP WebSocket 服务，它只是编辑器；真正启动 WebSocket 服务器的是 PHP 命令行（php），而 VS Code 的作用是写代码、调试、发送请求——配置关键在于选对 PHP WebSocket 库、避开 fsockopen 权限陷阱、用好终端和调试器。
PHP WebSocket 服务不能靠 php -S 启动
php -S 是内置的 HTTP 服务器，只处理 HTTP 请求，无法响应 WebSocket 协议升级（Upgrade: websocket）。强行用它跑 WebSocket 会卡在握手阶段，浏览器报错 WebSocket connection to 'ws://...' failed: Error during WebSocket handshake。
必须用支持长连接和 I/O 多路复用的库，例如：
-
textalk/websocket：纯客户端，不能当服务端 -
ratchet/pawl：客户端库，也不行 - ✅ 正确选择：
ratchet/rfc6455（即cboden/ratchet）或更现代的reactphp/socket+evenement/event-emitter
推荐起步用 cboden/ratchet，它封装了握手、帧解析、连接管理，且文档清晰。安装命令：
立即学习“PHP免费学习笔记（深入）”；
composer require cboden/ratchet
VS Code 终端里启动 WebSocket 服务的正确姿势
在 VS Code 内置终端（Ctrl+`）中执行 PHP 脚本时，必须确保：
- PHP 版本 ≥ 7.4（
ratchet2.x 要求） - 扩展
ext-sockets已启用（Windows 下默认关闭，Linux/macOS 通常已开）；检查方法：php -m | grep sockets - 脚本监听地址不能是
127.0.0.1:8080以外的私有地址（如localhost在某些系统解析慢，0.0.0.0可能被防火墙拦截）
一个最小可运行服务示例（保存为 ws-server.php）：
<?php
require __DIR__ . '/vendor/autoload.php';
use Ratchet\MessageComponentInterface;
use Ratchet\ConnectionInterface;
use Ratchet\Server\IoServer;
use Ratchet\Http\HttpServer;
use Ratchet\WebSocket\WsServer;
class Chat implements MessageComponentInterface {
protected $clients;
public function __construct() {
$this->clients = new \SplObjectStorage();
}
public function onOpen(ConnectionInterface $conn) {
$this->clients->attach($conn);
echo "New connection! ({$conn->resourceId})\n";
}
public function onMessage(ConnectionInterface $from, $msg) {
foreach ($this->clients as $client) {
if ($from !== $client) {
$client->send($msg);
}
}
}
public function onClose(ConnectionInterface $conn) {
$this->clients->detach($conn);
echo "Connection {$conn->resourceId} closed\n";
}
public function onError(ConnectionInterface $conn, \Exception $e) {
echo "An error occurred: {$e->getMessage()}\n";
$conn->close();
}
}
$server = IoServer::factory(
new HttpServer(new WsServer(new Chat())),
8080
);
$server->run();
在 VS Code 终端运行：php ws-server.php。若无输出卡住，说明已监听成功；若报错 PHP Warning: stream_socket_server(): unable to connect to tcp://127.0.0.1:8080，大概率是端口被占用或 sockets 扩展未启用。
前端连不上？检查浏览器 WebSocket URL 和 CORS
浏览器 JS 连接时，URL 必须与后端监听协议/地址严格匹配：
- 后端监听
127.0.0.1:8080→ 前端用ws://127.0.0.1:8080 - 不能写成
ws://localhost:8080（DNS 解析差异可能导致握手失败） - 不能写成
wss://（除非你配了 TLS，否则直接拒绝）
Ratchet 默认不设 CORS 头，但 WebSocket 协议本身不校验 Origin（HTTP 头里的 Origin 字段在握手阶段会被忽略），所以一般无需额外配置。真正导致连接失败的常见原因反而是：
- VS Code 终端里服务没在运行（忘记
php ws-server.php或按了Ctrl+C中断） - 前端页面通过
file://协议打开（Chrome 禁止该协议发起 WebSocket 连接），必须用http://（例如php -S 127.0.0.1:8000起个静态服务器） - 杀毒软件或 Windows 防火墙拦截了 8080 端口（临时关闭测试）
调试 WebSocket 消息：别依赖 var_dump()，改用 error_log() 或日志文件
WebSocket 是常驻进程，var_dump() 输出会卡在终端缓冲区，甚至不显示；echo 也容易因无换行符而堆积。可靠方式是写入日志文件：
// 替换掉所有 echo/var_dump
error_log(date('Y-m-d H:i:s') . " [OPEN] {$conn->resourceId}\n", 3, __DIR__.'/ws.log');
然后在 VS Code 中右键打开 ws.log，勾选「自动滚动到底部」，就能实时看到连接、收发、断开事件。注意日志路径要用绝对路径或基于 __DIR__，避免因工作目录变化导致写入失败。
真实项目中，WebSocket 逻辑一旦涉及用户状态、广播范围、心跳保活，复杂度会陡增——此时别硬扛，优先用 reactphp 生态或转投 Swoole（需编译扩展）。VS Code 能帮你写好代码、看清日志、连上调试器，但它不会替你解决协议细节和并发模型的问题。
