Laravel Sanctum本地运行正常但生产服务器返回未认证错误如何解决

1. 请求头校验 #

• 确认客户端请求头是否正确携带Authorization字段，固定格式为Bearer 你的有效token，注意Bearer与token值之间必须有1个半角空格。如果你的客户端使用自定义带下划线的请求头（比如access_token），需要检查Nginx配置是否开启underscores_in_headers on;，默认Nginx会直接丢弃带下划线的请求头，导致Sanctum无法获取到token。
• 确认请求头携带了Accept: application/json，未指定JSON接收类型的请求会被Sanctum判定为网页请求，默认走会话认证逻辑，自然会返回未认证错误。

2. 项目配置校验 #

• 检查config/sanctum.php中的stateful配置是否包含生产环境的API域名/IP，注意不要携带端口号，HTTPS站点要确保域名拼写完全正确。修改配置后必须执行php artisan config:cache重建配置缓存，否则新配置不会生效。
• 校验.env文件参数：
  • SANCTUM_STATEFUL_DOMAINS填写生产环境实际访问的API域名
  • SESSION_DOMAIN填写根域名（格式为.yourdomain.com，前面的半角点不可省略）
  • APP_URL与生产环境实际访问地址完全一致，HTTPS站点必须以https://开头
• 确认config/auth.php中api guard的驱动配置为sanctum：

'guards' => [
    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

3. 服务器配置校验 #

• 检查Nginx配置是否正确将Authorization头传递给PHP-FPM，在对应的站点配置location ~ \.php$块中添加以下规则：

fastcgi_pass_header Authorization;
fastcgi_param HTTP_AUTHORIZATION $http_authorization;

默认PHP-FPM配置会过滤掉Authorization头，导致Laravel无法拿到token值。

• 确认需要认证的API路由统一放在routes/api.php文件中，且正确绑定了auth:sanctum中间件，不要和web路由组的中间件混用。
• 检查Laravel存储目录权限，确保storage/、bootstrap/cache/目录的读写权限正常，权限设置为755即可，不要设置777开放所有权限。

4. 其他问题排查 #

• 检查personal_access_tokens表中对应token的expires_at字段是否未过期，tokenable_type、tokenable_id对应的用户模型存在且未被软删除。
• 生产环境HTTPS站点需将.env中的SESSION_SECURE_COOKIE设置为true，否则会话校验逻辑会失败。
• 依次执行以下命令清除所有缓存：

php artisan config:clear
php artisan route:clear
php artisan cache:clear

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