Laravel 9 Sanctum认证API生产环境路由无法访问问题排查

以下是针对API路由无法访问问题的逐一排查步骤：

1. 确认服务器虚拟主机指向正确 #

确保Web服务器（Apache/Nginx）的虚拟主机根目录指向项目的public文件夹，而非项目根目录，这是Laravel部署的常见错误：

• Apache：检查虚拟主机配置中的DocumentRoot应为/path/to/your-project/public
• Nginx：配置中的root字段需指向/path/to/your-project/public，同时包含重写规则：

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }
  

2. 验证URL重写配置 #

• Apache：确认mod_rewrite模块已启用，且public/.htaccess文件内容正确（默认Laravel配置即可）：

  <IfModule mod_rewrite.c>
      <IfModule mod_negotiation.c>
          Options -MultiViews -Indexes
      </IfModule>
  
      RewriteEngine On
  
      # Handle Authorization Header
      RewriteCond %{HTTP:Authorization} .
      RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
  
      # Redirect Trailing Slashes If Not A Folder...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_URI} (.+)/$
      RewriteRule ^ %1 [L,R=301]
  
      # Send Requests To Front Controller...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteRule ^ index.php [L]
  </IfModule>
  

• Nginx：确保上述重写规则已配置，否则Laravel无法解析路由。

3. 检查Sanctum与环境变量配置 #

在.env文件中确认以下关键配置：

• APP_URL=http://{ipAddress}（需与访问的IP/域名完全一致）
• SESSION_DOMAIN={ipAddress}（IP部署直接填IP，域名部署填对应域名）
• SANCTUM_STATEFUL_DOMAINS={ipAddress}（允许发起有状态请求的IP/域名，多个用逗号分隔）

4. 清除路由缓存 #

生产环境下Laravel可能缓存了旧路由规则，导致新增测试路由未生效，执行命令：

php artisan route:clear
# 如需重新缓存路由（可选）
php artisan route:cache

5. 验证目录权限 #

确保Laravel的storage和bootstrap/cache目录有Web服务器用户的写入权限：

chmod -R 755 storage bootstrap/cache
# 或根据服务器用户调整所有者
chown -R www-data:www-data storage bootstrap/cache

6. 检查路由定义与中间件 #

• 确认routes/api.php中的测试路由定义正确，且未被不必要的中间件拦截：

  // 无认证中间件的测试路由，优先验证基础访问
  Route::get('/test', function () {
      return response()->json(['status' => 'success', 'message' => 'Test route works']);
  });
  

• 检查RouteServiceProvider中的mapApiRoutes方法，确认API前缀为api：

  protected function mapApiRoutes()
  {
      Route::prefix('api')
           ->middleware('api')
           ->namespace($this->namespace)
           ->group(base_path('routes/api.php'));
  }
  

7. 排查服务器网络与防火墙 #

• 确认服务器的80/443端口已在防火墙/安全组中开放，外部能正常访问该IP的对应端口。
• 测试请求时使用匹配的HTTP方法（如GET对应路由的get方法），避免方法不匹配导致的405错误。

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