纯PHP路由线上站点失效：本地正常部署后返回404

你的路由实现逻辑上是成立的，但线上出现404的核心问题不在PHP代码，而是缺少服务器端的URL重写配置，同时代码也有可优化的地方，下面详细说明：

一、为什么本地正常，线上返回404？ #

• 本地开发时如果用的是PHP内置服务器（php -S localhost:3000），它会默认将所有请求转发到入口文件（比如你的index.php），所以$_SERVER['REQUEST_URI']能正确获取到请求路径，路由逻辑可以正常工作。
• 线上环境（Apache/Nginx）默认会优先寻找物理文件或目录：比如访问url.com/gallery时，服务器会直接去项目根目录找gallery文件夹或gallery.php文件，找不到就返回404，不会自动把请求转到你的入口文件，导致路由代码根本没机会执行。

二、解决线上404的关键：配置服务器URL重写 #

需要让服务器把所有非物理文件/目录的请求，都转发到你的入口文件（比如index.php），具体配置如下：

Apache环境 #

在项目根目录创建.htaccess文件，添加以下规则：

RewriteEngine On
# 如果请求的不是文件
RewriteCond %{REQUEST_FILENAME} !-f
# 如果请求的不是目录
RewriteCond %{REQUEST_FILENAME} !-d
# 将所有请求转发到index.php
RewriteRule ^(.*)$ index.php [QSA,L]

注意：要确保Apache开启了mod_rewrite模块。

Nginx环境 #

在你的站点配置文件中（比如/etc/nginx/sites-available/your-site.conf），找到location /块，修改为：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

修改后重启Nginx服务生效。

三、你的PHP路由代码优化建议 #

虽然逻辑可行，但代码结构和健壮性可以改进：

1. 分离路由逻辑与HTML结构：不要把PHP路由代码嵌在HTML的<body>里，应该把入口文件改成纯PHP，视图文件（比如homepage.php、gallery.php）单独存放HTML内容。
2. 处理URI的查询参数：原代码中如果请求带查询参数（比如/gallery?id=1），$_SERVER['REQUEST_URI']会包含?id=1，导致路由匹配失败，应该用parse_url提取纯路径。
3. 正确设置404状态码：返回404页面时，要设置HTTP响应码为404，避免搜索引擎误判。

优化后的示例代码：

<?php
$routes = [];

// 注册路由
function route(string $path, callable $callback) {
    global $routes;
    $routes[$path] = $callback;
}

// 执行路由匹配
function run() {
    global $routes;
    // 获取不带查询参数的纯路径
    $uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
    // 统一处理末尾斜杠（比如/gallery和/gallery/都能匹配）
    $uri = rtrim($uri, '/') ?: '/';

    // 匹配到路由则执行回调
    if (isset($routes[$uri])) {
        $routes[$uri]();
        exit;
    }

    // 404处理
    http_response_code(404);
    if (isset($routes['/404'])) {
        $routes['/404']();
    } else {
        echo "<h1>404 Not Found</h1>";
    }
}

// 定义路由
route('/', function () {
    require_once "pages/homepage/homepage.php";
});

route('/gallery', function () {
    require_once "pages/gallery/gallery.php";
});

route('/about_us', function () {
    require_once "pages/about_us/about_us.php";
});

route('/404', function () {
    require_once "pages/404/404.php";
});

run();
?>

总结 #

你的路由逻辑本身是正确的，但必须配置服务器的URL重写规则才能让线上环境生效，同时优化代码结构可以提升项目的可维护性。

内容的提问来源于stack exchange，提问作者addcommitpush