解决 PhpStorm 内置 Web 服务器 404 错误：快速排查指南

php

2025-01-07 06:35:19

PhpStorm 内置 Web 服务器 404 错误排查

PhpStorm 的内置 Web 服务器能提供快速便捷的本地开发环境。然而，有时会遇到它返回 404 错误的情况，这表示请求的资源找不到。这种问题可能由多种原因造成。了解这些常见原因和对应的解决方法对高效开发至关重要。

项目根目录配置问题

最常见的问题是 PhpStorm 的配置未正确指定项目根目录。内置 Web 服务器会尝试从这个目录中提供文件，如果目录设置错误，自然会出现 404 错误。

解决方案:

进入 File -> Settings (或者在 macOS 上 PhpStorm -> Preferences)。
在 Settings 窗口中，找到 Languages & Frameworks -> PHP -> Servers。
检查服务器的设置。Host 应当为 localhost 或 127.0.0.1，Port 为你想要的端口。最重要的是检查 Document root 是否指向你的项目根目录的正确路径。确保它是项目的主入口文件的父级目录，例如，包含 index.php 的目录。
如果目录不正确，点击右侧的浏览按钮 ... 并选择你的项目根目录。
保存设置，并重新运行内置 Web 服务器。

这个配置过程的关键是让 PhpStorm 的内置服务器知道应该在哪里查找你的项目文件。正确的配置确保了浏览器请求能映射到服务器文件。

路由和 `.htaccess` 文件

除了项目根目录问题外，另一个可能的原因是 Web 服务器的请求路由未能正确解析。如果你使用了 .htaccess 文件来配置 Apache 服务器的重写规则，但是 PhpStorm 的内置服务器默认不支持这些规则。当尝试访问路由时，服务器找不到对应的资源，就会返回 404 错误。

解决方案:

一种解决方案是使用 PHP 路由脚本。创建一个 index.php 文件作为入口文件，并处理路由请求。这使你能掌控应用的 URL 处理。

示例 index.php:

<?php

$requestUri = $_SERVER['REQUEST_URI'];

if ($requestUri === '/about') {
    include 'about.php';
} elseif ($requestUri === '/') {
  include 'home.php';
}else {
    http_response_code(404);
    echo '404 - Page not found';
}

这个代码示例，展示了一个简单的路由脚本。$_SERVER['REQUEST_URI'] 获取当前请求的 URI，根据不同的 URI 引入对应的 PHP 文件。这部分要与自己应用的实际路由相匹配，进行扩展和定制。你需要按照自己的实际路由，完善代码。

这种方法允许完全自定义路由，但也可能需要更多的开发工作。一种替代方案是设置更全面的开发环境，例如，使用 Docker 并集成 Nginx 或 Apache 来提供本地服务器环境。但这种方法通常设置较为复杂。

文件访问权限

有时 404 错误也可能是由于服务器没有访问请求文件或文件夹的正确权限引起的。这种情况在一些 Unix 类系统上较为常见。

解决方案:

使用如下命令确保 Web 服务器能访问文件：

chmod -R 755 /path/to/your/project

请注意将 /path/to/your/project 替换成你项目的实际路径。此命令会更改项目目录及其子目录下所有文件和文件夹的权限。755 权限允许所有用户读取和执行文件，但只有所有者才能写入文件，这是个比较合理的默认设置。
此命令会确保 Web 服务器的用户，也就是当前运行 PhpStorm 的用户，拥有读取项目文件的权限。

CLI 解析器配置与 `php.ini`

PhpStorm 要求你设置 CLI（命令行）PHP 解析器。此设置通常独立于内置 Web 服务器，但在极少数情况下，不正确的 PHP CLI 配置会导致问题。特别是，错误配置或者更改 php.ini 配置可能影响 Web 服务器的行为。虽然上述问题图中显示已经设置 CLI 解析器，但是确保配置正确依然重要。

解决方案:

进入 File -> Settings (或者在 macOS 上 PhpStorm -> Preferences)。
在 Settings 窗口中，找到 Languages & Frameworks -> PHP。
确保已选择正确的 CLI Interpreter。如果未配置，点击右边的 ... 按钮并添加一个新的。选择本地安装的 PHP 解释器的路径。
仔细检查是否使用的是正确的 php.ini 文件，且其设置是否和预期一致，包括相关扩展的加载情况等。检查关键配置，例如 error reporting 设置和 enable short tag 等配置。在排除错误时，也可以尝试取消特定选项或扩展进行问题定位。
如果已经将 php.ini-development 重命名为 php.ini,确认 php.ini 文件没有其他错误设置，必要时可以使用原本的 php.ini-development 配置进行替换排查。