Symfony WebServerBundle五大控制台命令全清单:server:run、start、stop、status、log实战示例
Symfony WebServerBundle五大控制台命令全清单:server:run、start、stop、status、log实战示例
Symfony WebServerBundle 是 Symfony 生态中用于本地开发的 Web 服务器命令包,它封装了 server:run、server:start、server:stop、server:status、server:log 五大控制台命令,让你无需配置 Apache 或 Nginx,一条命令就能用 PHP 内置 Web 服务器跑起整个项目 👇
WebServerBundle 是什么?
WebServerBundle 的设计目标很简单:简化本地开发环境。传统方式下你要装好 Apache/Nginx、配好虚拟主机、设置 DOCUMENT_ROOT,而现在只需一条 php bin/console 命令。
它的工作原理是:通过 Symfony\Component\Process 启动 PHP 自带的命令行 Web 服务器,并用内置的 router.php 脚本模拟 .htaccess 的 rewrite 规则,把请求转发给前控制器(app.php / index.php 等),相关逻辑见 WebServer.php。
⚠️ 注意:自 Symfony 4.4 起该 Bundle 已标记为 deprecated,5.0 中移除,官方推荐使用 Symfony 本地 Web 服务器(
bin/symfony server:run)。但理解这五大命令,对掌握 Symfony 本地开发流程仍然非常有用。
五大命令速查清单
| 命令 | 作用 | 是否阻塞终端 | 源码位置 |
|---|---|---|---|
server:run |
前台运行本地 Web 服务器 | ✅ 阻塞(Ctrl+C 停止) | ServerRunCommand.php |
server:start |
后台启动 Web 服务器 | ❌ 后台进程 | ServerStartCommand.php |
server:stop |
停止后台服务器 | ❌ | ServerStopCommand.php |
server:status |
查看服务器监听状态 | ❌ | ServerStatusCommand.php |
server:log |
实时显示应用日志 | ✅ 阻塞 | ServerLogCommand.php |
这五个命令通过服务定义文件 webserver.xml 注册为 console.command,安装 Bundle 后即可使用。
一键安装与启动:server:run
先安装(开发环境依赖):
composer require --dev symfony/web-server-bundle
然后前台启动服务器:
php bin/console server:run
默认行为(见 WebServerConfig.php):
- 监听地址
127.0.0.1,从 8000 端口开始自动寻找第一个空闲端口 - 默认文档根目录为
public/(可被composer.json中extra.public-dir覆盖,逻辑在 WebServerExtension.php) - 启动成功后终端提示
Server listening on http://127.0.0.1:8000
实战示例:
# 指定地址和端口
php bin/console server:run 127.0.0.1:8080
# 只传端口
php bin/console server:run 8080
# 修改文档根目录
php bin/console server:run --docroot=htdocs/
# 使用自定义路由脚本(默认是 Resources/router.php)
php bin/console server:run --router=app/config/router.php
server:run 会阻塞当前终端,按 Control+C 即可停止。另外源码中明确提示:在 prod 环境运行该服务器不被推荐(见 ServerRunCommand.php)。
后台常驻方案:server:start
需要"边跑服务边执行其他命令"时,用 server:start 把服务器放到后台进程运行:
php bin/console server:start # 后台启动
php bin/console server:start 8080 # 指定端口
php bin/console server:start --pidfile=.my-pid # 自定义 PID 文件
它通过 pcntl_fork() 派生子进程并写入 PID 文件(默认 .web-server-pid),核心实现见 WebServer.php:
$pid = pcntl_fork();
...
file_put_contents($pidFile, $config->getAddress());
两个实用细节:
- 依赖 pcntl 扩展。没有该扩展时命令会报错,并交互式询问是否改用
server:run(ServerStartCommand.php) - 重复启动会被拒绝。再次执行
server:start时会提示 "The web server has already been started",需先执行server:stop
优雅停机:server:stop
停止 server:start 启动的后台服务器:
php bin/console server:stop
php bin/console server:stop --pidfile=.my-pid # 对应自定义 PID 文件
它的原理很轻巧:删除 PID 文件后,server:start 的守护循环检测到文件消失就会调用 $process->stop() 终止子进程(见 WebServer.php 与 stop 方法):
// stop the web server when the lock file is removed
while ($process->isRunning()) {
if (!file_exists($pidFile)) {
$process->stop();
}
sleep(1);
}
如果服务器没在运行,server:stop 会报错 No web server is listening.,属于正常提示。
状态体检:server:status
检查后台服务器是否还活着、监听在哪个地址:
php bin/console server:status
输出示例:
[OK] Web server still listening on http://127.0.0.1:8000
--filter 选项可以让输出变成机器可读格式,方便写进 Shell 脚本取端口号:
php bin/console server:status --filter=port # 输出: 8000
php bin/console server:status --filter=host # 输出: 127.0.0.1
php bin/console server:status --filter=address # 输出: 127.0.0.1:8000
--filter 只接受 port、host、address 三个值,传其他值会抛出 InvalidArgumentException(见 ServerStatusCommand.php)。状态检测本身是一次真实的 socket 连接探测,连接失败时还会自动清理过期的 PID 文件(isRunning 方法)。
实时日志面板:server:log
server:log 启动一个日志接收服务器,把应用运行时产生的日志实时渲染到终端,不同客户端还会用不同背景色区分(ServerLogCommand.php):
php bin/console server:log
常用选项:
# 修改监听地址(默认 0.0.0.0:9911)
php bin/console server:log --host=127.0.0.1:9999
# 自定义日志行格式 / 日期格式
php bin/console server:log --format="%datetime% %channel%: %message%"
# 用表达式语言过滤日志
php bin/console server:log --filter="level > 200 or channel in ['app', 'doctrine']"
两点注意:
- 该命令依赖
symfony/monolog-bridge(composer.json),缺失时命令会自动隐藏不注册 - 使用
--filter还需额外安装symfony/expression-language,否则抛出LogicException
常见问题与最佳实践
Q1:8000 端口被占用了怎么办?
不传地址参数时,配置类会自动向上探测空闲端口(8000 起,最多到 8100),见 findBestPort;探测失败会提示 Unable to find a port available to run the web server.
Q2:为什么提示 "A process is already listening on http://..."?
说明该地址已有服务器在监听。先 server:stop,或换一个端口启动。
Q3:server:run 和 server:start 怎么选?
- 本地写代码调试 →
server:run(前台,方便看输出、Ctrl+C 即停) - 跑自动化测试、演示环境 →
server:start(后台常驻,配合server:status/server:stop)
Q4:新项目该怎么选?
Symfony 4.4+ 项目建议直接使用内置的 Symfony Local Web Server(bin/symfony server:run),功能更完整;本 Bundle 五大命令更适合作为理解"用 PHP 内置服务器 + router 脚本"这一机制的入门范例。
小结
- 🚀
server:run:前台快速启动,默认127.0.0.1:8000起自动找空闲端口 - 🌫
server:start:后台常驻,依赖pcntl,写入.web-server-pid - ✋
server:stop:删除 PID 文件触发停机 - 🔍
server:status:状态检查 +--filter机器可读输出 - 📜
server:log:实时日志终端,支持表达式过滤
五个命令覆盖了"启动 → 查看 → 过滤日志 → 停止"的完整本地开发闭环。相关源码可按需对照:命令定义在 Command/ 目录,进程管理在 WebServer.php,地址与端口解析在 WebServerConfig.php。