最稳妥方式是用 Route::prefix('v1') 配合 ->namespace('App\Http\Controllers\V1') 组合，在 routes/api.php 中定义；需确保控制器真实存在于对应命名空间路径下，且不重复添加 /api 前缀。
在 Laravel 中给 API 接口路由加版本号 v1，最稳妥、原生支持、工具链兼容性最好的方式是 用 Route::prefix() 配合 namespace()，写在 routes/api.php 里。
✅ 正确做法：前缀 + 命名空间组合
// routes/api.php
Route::prefix('v1')
->namespace('App\Http\Controllers\V1')
->group(function () {
Route::get('/users', [UserController::class, 'index']);
Route::post('/users', [UserController::class, 'store']);
Route::apiResource('/posts', PostController::class);
});
这样访问 /api/v1/users 就会自动调用 App\Http\Controllers\V1\UserController 的 index 方法。
⚠️ 注意：Laravel 默认已在
RouteServiceProvider中为api.php加了/api前缀，所以你不用再写/api/v1，只写v1即可。否则路径会变成/api/api/v1/…。
? 控制器要放在对应命名空间下
确保你的控制器真实存在且路径匹配：
app/Http/Controllers/V1/UserController.php
内容类似：
<?php namespace App\Http\Controllers\V1;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
public function index()
{
return response()->json(['version' => 'v1']);
}
}
❌ 常见错误
- 只写
Route::prefix('v1')却不加->namespace(...)→ Laravel 还是去找App\Http\Controllers\UserController，报错 Class not found。 - 路由里写
'UserController@index'字符串 → 自动加载失败，必须用UserController::class写法。 - 在
routes/api.php顶层又套一层Route::prefix('api')→ 导致 URL 多出一个/api。
? 后续扩展 v2 很简单
复制一份，改前缀和命名空间即可：
Route::prefix('v2')
->namespace('App\Http\Controllers\V2')
->group(function () {
Route::get('/users', [UserController::class, 'index']);
// v2 可以返回不同字段、加新校验等
});
控制器放在 app/Http/Controllers/V2/ 下，完全隔离，互不影响。
不复杂但容易忽略细节，关键是前缀和命名空间必须配对，控制器类路径必须真实存在。
