PHP 8.4本身不提供API版本管理，需靠路由分发与逻辑隔离实现；应通过parse_url()和preg_match('|^/api/(v\d+)/|')提取版本，校验后加载对应控制器，并用只读DTO+适配层保障旧接口字段兼容性。
PHP 8.4 本身不提供 API 版本管理功能，它只是运行环境；真正的版本控制靠的是路由分发、请求解析和逻辑隔离策略。直接用 PHP 8.4 原生写（不依赖框架）也能做，但必须手动处理版本识别、控制器加载和响应兼容性——否则旧接口一升级就崩。
怎么从 URL 路径提取并路由到对应版本控制器
PHP 8.4 的 parse_url() 和 preg_match() 足够可靠，但要注意正则边界和空版本兜底：
- 用
^/api/(v\d+)/匹配，避免误匹配/apiv1/这类非标准路径 - 必须校验
$matches[1]是否在允许范围内（如只支持v1和v2），否则返回400 Bad Request - 路径中带点号（如
/api/v1.5/）会被parse_url()截断，建议禁用小数版号，统一用整数 - 示例代码片段：
if (! $uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)) { http_response_code(400); exit(json_encode(['error' => 'Invalid URI'])); } if (preg_match('|^/api/(v\d+)/|', $uri, $matches)) { $version = $matches[1]; if (! in_array($version, ['v1', 'v2'])) { http_response_code(400); exit(json_encode(['error' => 'Unsupported API version'])); } require_once "controllers/{$version}/UserController.php"; } else { http_response_code(404); exit(json_encode(['error' => 'Not found'])); }
如何让 v1 接口在 v2 上线后继续返回旧字段结构
不能靠“复制粘贴旧代码”，得用适配层把新服务结果转成旧格式。PHP 8.4 的联合类型和只读类能帮你写更安全的转换逻辑：
- 定义
v1专用 DTO 类，用readonly属性 + 构造器约束字段名和类型 - 在
v2业务逻辑执行完后，显式调用V1UserDto::fromV2($user)转换，而不是在 JSON encode 前临时unset()字段 - 禁止在
v1控制器里直接调用v2的 service 方法并删字段——那会把兼容逻辑散落在各处，难维护 - 新增字段必须设默认值（如
'email' => null），不能留空或抛异常，否则老客户端解析 JSON 会失败
Header 版本控制调试时为什么总走不到 v2
因为 PHP 8.4 默认不解析 Accept 头里的 vendor MIME 类型，$_SERVER['HTTP_ACCEPT'] 是原始字符串，得自己切分：
立即学习“PHP免费学习笔记（深入）”；
- 不要用
strpos($header, 'v2')——可能匹配到v2.1或av2，要用preg_match('/v2(?![.\d])/', $header) - Chrome 浏览器地址栏直输 URL 不会自动带
Accept，必须用curl或 Postman 手动加头：-H "Accept: application/vnd.myapp.v2+json" - Laravel/Symfony 等框架会自动标准化 header 名（
X-API-Version→HTTP_X_API_VERSION），但原生 PHP 不会，$_SERVER键名严格区分大小写和连字符 - 如果用了 Nginx，确认没开启
underscores_in_headers off;，否则下划线 header 会被丢弃
最易被忽略的点：数据库字段变更和 API 版本不是一回事。哪怕你只加了一个 is_verified 字段，如果 v1 接口响应里没这个字段，就不能在 SQL 查询里 SELECT 它——得在 service 层做条件投影，而不是靠 MySQL 视图或 ORM 全量查再过滤。否则性能毛刺和内存溢出会在某次批量请求时突然爆发。
