在Ubuntu上使用 PHPStorm 开发 REST API 的实操指南
一 环境准备
- 安装 PHP 与常用扩展（建议 PHP 8.1+）：sudo apt update && sudo apt install -y php php-cli php-mbstring php-curl php-json php-xml php-mysql
- 安装 Composer：sudo apt install -y composer
- 安装 数据库（如 MySQL）：sudo apt install -y mysql-server，随后执行 sudo mysql_secure_installation 完成初始化
- 安装 Web 服务器（二选一或并行）：
- Apache：sudo apt install -y apache2 && sudo a2enmod php && sudo systemctl restart apache2
- 或使用 PHP 内置服务器 进行开发：php -S 127.0.0.1:8000
- 安装 PHPStorm：从 JetBrains 下载 Linux 版，解压后运行 bin/phpstorm.sh 启动；首次运行按向导完成配置
二 创建项目与框架选择
- 新建项目：在 PHPStorm 欢迎页选择 New Project，语言选择 PHP，选择项目目录；在终端执行 composer init 初始化依赖管理
- 选择框架（任选其一，便于快速构建 REST API）：
- Laravel：composer create-project laravel/laravel api && cd api
- Slim：composer require slim/slim:^4
- 建议启用 PHP 内置服务器 进行本地开发：php -S 127.0.0.1:8000 -t public（Laravel 使用 public 目录为入口）
三 在 PHPStorm 中配置运行与调试
- 配置 PHP 解释器：File → Settings → Languages & Frameworks → PHP → Add → PHP Executable，选择 /usr/bin/php
- 配置 内置服务器运行：Run → Edit Configurations → + → PHP Built-in Web Server，设置 Host: 127.0.0.1、Port: 8000、Document root: <项目>/public
- 配置 Xdebug 3（推荐）：
- 安装：sudo apt install -y php-xdebug
- 在 php.ini 或 /etc/php//mods-available/xdebug.ini 追加：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- 在 PHPStorm：Settings → PHP → Debug 将 Debug port 设为 9003；Run → Edit Configurations → 选择你的运行项，勾选 Break at first line in PHP scripts；调试时点击工具栏 Start Listening for PHP Debug Connections 图标，浏览器访问对应路由触发断点
四 使用内置 HTTP 客户端测试 API
- 打开 Tools → HTTP Client → Create New Request，新建 .http 文件，编写请求示例：
-
GET http://127.0.0.1:8000/api/users
Accept: application/json
-
POST http://127.0.0.1:8000/api/users
Content-Type: application/json
{
“name”: “Alice”,
“email”: “alice@example.com”
}
- 点击请求左侧 Run 图标发送请求，查看 Response、Headers、Status 等；可将请求保存为 .http 文件纳入版本控制，便于回归测试与团队协作
五 常见问题与排查
- 访问 404：确认路由已注册、请求路径正确；使用内置服务器时确保 Document root 指向 public（Laravel），或路由前缀与框架配置一致
- 断点不生效：确认 Xdebug 端口=9003 且未被 php-fpm 占用；PHPStorm 已开启 Start Listening；运行配置与项目实际 Host/Port 一致
- 内置服务器端口冲突：更换端口（如 8001），并同步修改运行配置与请求地址
- 数据库无法连接：在 PHPStorm → Database 添加 MySQL 数据源，填写 Host: localhost、Port: 3306、用户名与密码，使用 Test Connection 验证；确保 MySQL 服务已启动且用户权限正确
