Laravel接口返回默认HTML页面，自定义Auth控制器失效问题排查

我尝试通过自定义Auth控制器实现用户注册功能（使用Laravel默认未修改的User模型），但向/api/register发送POST请求时，返回的是默认HTML页面，而非预期的JSON响应。应用仅作为后端服务，无需视图配置，请问哪里操作有误？

自定义Auth控制器代码 #

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        //validate the request
        $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:8|confirmed',
        ]);

        $data = $request->all();

        //create new user
        $user = User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => Hash::make($data['password']),
        ]);

        //return response
        return response()->json(['message' => 'Successfully created user!'], 201);
    }
}

API路由配置（api.php） #

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\AuthController;


Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

Route::post('/register', [AuthController::class, 'register']);

解决方案 #

1. 确保请求头正确设置 #

向接口发送请求时，必须在请求头中添加Accept: application/json，让Laravel明确知道需要返回JSON格式的响应。如果请求体是JSON格式，同时要设置Content-Type: application/json。

2. 强制验证失败时返回JSON响应 #

如果请求头设置正确但仍返回HTML，可能是验证失败时的响应格式问题。可以修改验证代码，明确指定验证器使用JSON响应：

$request->validate(
    [
        'name' => 'required|string|max:255',
        'email' => 'required|string|email|max:255|unique:users',
        'password' => 'required|string|min:8|confirmed',
    ],
    [], // 自定义错误消息（可选）
    [], // 自定义属性名称（可选）
    'json' // 指定验证器的响应格式为JSON
);

或者全局配置验证异常处理：在app/Exceptions/Handler.php的register方法中添加以下代码，确保所有API请求的验证异常返回JSON：

use Illuminate\Validation\ValidationException;

$this->renderable(function (ValidationException $e, $request) {
    if ($request->is('api/*')) {
        return response()->json([
            'message' => '验证失败',
            'errors' => $e->errors()
        ], 422);
    }
});

3. 检查路由中间件 #

确认api.php中的路由没有被错误地应用web中间件。默认情况下，api路由组已经使用了api中间件组（包含throttle、bindings等），如果混入web中间件，可能会触发CSRF验证或会话相关的重定向，导致返回HTML页面。

4. 确认路由匹配正确 #

运行php artisan route:list命令，查看/api/register路由是否存在，请求方法是否为POST，控制器方法是否正确关联。同时检查请求URL是否正确，避免因服务器配置（如Nginx/Apache的重写规则）导致路由不匹配，返回404的HTML页面。

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