Laravel Passport开发的REST API部署Hostinger子域名后线上无法运行

按以下优先级逐一排查，覆盖绝大多数部署场景的常见问题：

• 修正子域名根目录配置
  Hostinger子域名的网站根目录必须指向Laravel项目的public文件夹，不能直接指向项目根目录。举个例子，如果项目代码上传在public_html/api路径下，子域名api.website.com的根目录要设置为/public_html/api/public。同时确认public目录下Laravel自带的.htaccess文件已完整上传，FTP传输时隐藏文件容易被漏传，缺失会导致路由重写规则失效，所有接口直接返回404。
• 配置正确的文件权限
  项目内的storage、bootstrap/cache两个目录必须给运行PHP的用户分配可写权限，SSH进入项目根目录执行以下命令递归设置即可，不要用777权限，存在安全隐患：

  chmod -R 755 storage bootstrap/cache
  

• 完成线上环境初始化
  1. 核对线上.env配置：数据库连接地址、库名、账号密码替换为Hostinger面板提供的MySQL参数（注意Hostinger的数据库主机不是默认的localhost，以面板显示的专属地址为准），APP_URL项设置为https://api.website.com，调试阶段可以临时把APP_DEBUG设为true直接在页面看报错，排查完再改回false。
  2. 重新生成核心密钥：本地生成的应用密钥、Passport加密密钥不能直接在线上复用，是鉴权失败、500报错的高频原因，执行以下命令重新生成：

     php artisan key:generate
     php artisan passport:keys
     php artisan passport:install
     

  3. 清理冗余缓存：本地开发生成的配置、路由缓存带到线上会直接导致配置不生效，执行以下命令全量清理：

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

  4. 执行数据库迁移：确认数据库连接正常后，执行迁移命令创建业务表、Passport所需的鉴权相关表：

     php artisan migrate
     

• 核对PHP版本与扩展
  在Hostinger面板的PHP配置页，选择和本地Laravel版本匹配的PHP版本：Laravel 10要求PHP≥8.1，Laravel 9要求PHP≥8.0，Laravel 8要求PHP≥7.3。同时确认已开启以下必填扩展：bcmath、ctype、fileinfo、mbstring、openssl、pdo_mysql、tokenizer、xml，Passport依赖openssl扩展做加解密运算，未开启会直接抛出500错误。
• 核对请求规则与HTTPS配置
  1. 没有手动修改路由前缀的前提下，routes/api.php中定义的接口默认带/api前缀，Postman测试时不要漏写前缀，比如登录接口的正确地址是https://api.website.com/api/login，不是根路径下的/login。
  2. 在Hostinger面板为子域名一键申请Let's Encrypt免费SSL证书，开启强制HTTPS；临时测试阶段可以暂时关闭Postman设置中的SSL证书校验选项，排除证书信任问题导致的连接失败。
• 精准定位错误
  以上步骤排查完仍无法正常访问的，直接打开项目storage/logs/目录下的最新日志文件，根据日志中记录的具体报错信息定位问题即可，不需要盲目试错。

内容的提问来源于stack exchange，提问作者Christian Psalm Dimafelix