Laravel 11+Laradock环境下Sanctum API遇419 CSRF令牌不匹配问题

针对你在Laradock多项目环境中部署Laravel 11时遇到的419错误，以下是具体排查和解决步骤：

1. 确认XSRF令牌获取路径正确性 #

Laravel Sanctum的CSRF令牌必须通过/sanctum/csrf-cookie端点获取，预请求脚本要请求该路径，而非其他接口。如果你的预请求脚本请求的是其他地址，会导致获取的令牌无效。

2. 修正Postman请求头与Cookie配置 #

• 预请求拿到XSRF-TOKEN后，需将其值设置到请求头的X-XSRF-TOKEN字段（注意字段名是X-XSRF-TOKEN，不是XSRF-TOKEN）。
• 开启Postman的Send cookies选项（在请求的Cookies标签页中启用），因为supports_credentials开启后，会话Cookie需要随请求一起传递。
• 正确的预请求脚本示例：

  pm.sendRequest('http://laravel.api.test/sanctum/csrf-cookie', function (err, res) {
      if (!err) {
          const xsrfToken = pm.cookies.get('XSRF-TOKEN');
          pm.request.headers.add({key: 'X-XSRF-TOKEN', value: xsrfToken});
      }
  });
  

3. 验证.env配置并清除缓存 #

• 确保SESSION_DOMAIN设置为.api.test（前缀的点不可少，确保子域名laravel.api.test能共享会话），SANCTUM_STATEFUL_DOMAINS包含laravel.api.test，可额外添加本地开发域名避免环境问题：

  SESSION_DOMAIN=.api.test
  SANCTUM_STATEFUL_DOMAINS=laravel.api.test,localhost,127.0.0.1
  

• 执行php artisan config:clear清除配置缓存，确保新配置生效（Laradock容器内执行该命令，或通过docker-compose exec workspace bash进入容器后操作）。

4. 完善CORS配置细节 #

在config/cors.php中，确保以下配置正确：

return [
    'paths' => ['api/*', 'sanctum/csrf-cookie', 'auth/login'],
    'allowed_origins' => ['http://laravel.api.test'],
    'allowed_methods' => ['*'],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => true,
];

• paths必须包含/sanctum/csrf-cookie和/auth/login；
• allowed_origins明确指定你的项目域名，测试阶段可临时用['*']验证；
• supports_credentials保持为true。

5. 处理Laradock多项目会话冲突 #

多项目环境下，需确保每个项目的会话Cookie名称唯一，避免互相干扰：

SESSION_COOKIE_NAME=laravel_api_session

同时检查Laradock容器内的storage/framework/sessions目录权限，执行chmod -R 775 storage确保Laravel有读写权限（容器内操作）。

6. 检查路由与中间件配置 #

• 由于你的登录路由在routes/web.php中，web中间件组默认包含VerifyCsrfToken，需确保该中间件能正确识别X-XSRF-TOKEN请求头；
• 确认bootstrap/app.php中已正确启用statefulApi中间件：

  return Application::configure(basePath: dirname(__DIR__))
      ->withRouting(
          web: __DIR__.'/../routes/web.php',
          api: __DIR__.'/../routes/api.php',
          commands: __DIR__.'/../routes/console.php',
          health: '/up',
      )
      ->withMiddleware(function (Middleware $middleware) {
          $middleware->statefulApi();
      })
      ->create();
  

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