ThinkPHP伪静态规则在Vercel上的配置与使用指南

在Vercel平台部署ThinkPHP应用时，伪静态规则配置不当导致页面持续返回404错误，是许多开发者遇到的典型难题。其根本原因在于，Vercel采用的Serverless架构与传统Apache或Nginx服务器存在显著差异。它既不支持通过.htaccess或nginx.conf文件来配置重写规则，默认情况下还会对REQUEST_URI进行截断处理，致使ThinkPHP路由解析所依赖的PATH_INFO信息丢失。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

因此，一个至关重要的结论是：直接将Apache或Nginx的重写规则复制到Vercel是无效的。Vercel的URL重写逻辑完全由项目根目录下的vercel.json配置文件控制。而ThinkPHP的PATHINFO模式，恰恰需要依赖$_SERVER['PATH_INFO']或$_SERVER['REQUEST_URI']来识别路由。问题的症结在于，Vercel默认不会将完整的原始请求路径传递给PHP运行时环境，特别是在使用Build Output API的边缘函数场景中，路径信息在传递过程中就可能被“过滤”掉。

Vercel 部署 ThinkPHP 为何频繁出现 404 错误？

让我们深入剖析这一技术问题的根源。Vercel对PHP的支持基于Serverless Functions（例如@vercel/php运行时），它会将HTTP请求映射为标准CGI环境变量。然而，在此过程中，平台可能会对REQUEST_URI进行截断或标准化处理。

举例来说，当用户访问URL路径/user/profile/123时，传递到PHP运行环境的$_SERVER['REQUEST_URI']可能只剩下/index.php，后续的路径参数全部丢失。这样一来，ThinkPHP的路由系统无法接收到s=/user/profile/123或/user/profile/123这样的原始路径信息，返回404错误便在所难免。

• 开发者熟悉的Apache重写规则RewriteRule ^(.*)$ index.php/$1在Vercel上完全失效，因为其运行环境不包含mod_rewrite模块。
• 同样，Nginx配置中常见的if (!-e $request_filename) { ... }（判断文件是否存在后重写）逻辑，Vercel也不会解析执行。
• 最终结果是，ThinkPHP默认的URL_MODEL=2（即PATHINFO模式）在Vercel环境下极有可能无法正常工作，$_SERVER['PATH_INFO']经常为空或不可用。

解决方案：切换至 URL_MODEL=3（兼容模式）并配置 vercel.json

那么，如何解决Vercel上ThinkPHP的伪静态问题？答案是调整ThinkPHP的URL模式。从ThinkPHP 5.1及以上版本开始，支持URL_MODEL=3，即“兼容模式”。该模式的巧妙之处在于，它将所有路由参数通过查询字符串（Query String）进行传递，例如/index.php?s=/user/profile/123。

这种URL结构对Vercel平台非常友好，因为查询字符串是HTTP协议的标准组成部分，能够被完整保留并传递至PHP的$_GET全局变量中。

• 首先，在ThinkPHP的配置文件config/app.php中，将'url_model'参数的值修改为3（注意，不是默认的2）。
• 确保你的应用入口文件是public/index.php，并且已在配置中启用路由功能：'url_route_on' => true。
• 一个关键的最佳实践是：项目内部所有链接的生成，都应使用ThinkPHP内置的url()助手函数，避免手动编写硬编码的URL路径，这样才能确保生成的链接符合兼容模式的格式要求。

如何正确编写 vercel.json 重写规则？

URL模式切换完成后，接下来需要告知Vercel如何正确地转发请求。我们的核心目标是：将所有非静态资源的访问请求（例如/user/profile/123），统一转发到public/index.php这个入口文件，并自动附加s=参数。

这里有一个重要细节：Vercel的rewrite规则不支持像Nginx那样，在destination字段中直接使用正则表达式捕获的变量（如$1）。我们需要通过query字段来手动拼接参数。

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/public/index.php",
      "query": {
        "s": "/$1"
      }
    }
  ]
}

• source: "/(.*)" 会匹配所有请求路径（包括根路径/）。但请注意，Vercel会优先匹配并返回实际存在的静态文件（例如/css/app.css），因此你需要确保public/目录下已存放了相应的静态资源。
• destination 必须明确指向实际的PHP入口文件路径，即/public/index.php，不能简写为index.php或使用相对路径。
• query.s 是整个规则的核心。ThinkPHP在兼容模式下，会从$_GET['s']中解析路由信息，不再依赖于PATH_INFO。
• 不要在重写规则中添加has条件（例如判断请求的文件是否存在）。Vercel的文件存在性检查发生在边缘网络层，PHP运行时无法感知，添加此类条件反而可能干扰重写逻辑的正确执行。

常见部署问题排查：public 目录结构与构建输出

配置正确但部署依然失败？问题可能出在项目目录结构或构建输出环节。Vercel在构建项目时，默认将整个项目根目录视为Web服务的根目录。然而，ThinkPHP的标准目录结构要求Web入口必须位于public/子目录下。若不进行特殊处理，index.php可能会无法正确加载框架的核心文件或配置文件。

• 在vercel.json配置文件中，通过"builds"字段显式指定PHP入口文件：

  "builds": [
    {
      "src": "public/index.php",
      "use": "@vercel/php"
    }
  ]

• 确保public/目录下包含了完整的ThinkPHP引导文件（如index.php, .htaccess等）。而vendor/（Composer依赖）和thinkphp/（框架核心）目录应通过Composer安装在项目根目录，并由public/index.php正确引用。
• 切勿将.env这类包含敏感信息的环境配置文件放置在public/目录下，以免引发安全风险。Vercel的环境变量应通过其项目设置面板进行统一配置和管理。
• 若你的项目部署在子目录路径下（例如https://yourdomain.com/blog/xxx），则vercel.json中的source规则需要包含此前缀："source": "/blog/(.*)"。同时，别忘了在ThinkPHP的配置中设置'url_domain_root' => '/blog'以确保链接生成正确。

最后，一个最容易被忽视的关键点是：Vercel的PHP运行时不会自动设置PATH_INFO环境变量。这意味着，即使你强制使用URL_MODEL=2，并尝试在vercel.json中模拟PATH_INFO，也很可能因环境差异而失败。因此，直接切换到URL_MODEL=3（兼容模式）是目前在Vercel上部署ThinkPHP应用最稳定、最可靠的解决方案，建议开发者避免再在PATHINFO模式上耗费精力。