Laravel Inertia部署到共享主机返回空白显示@routes 求正确部署方案

问题根源 #

@routes字符串直接输出到页面，是因为Laravel的Blade模板指令没有被正常解析，服务器直接返回了未编译的模板原始内容。该问题90%以上的场景都是共享主机站点根目录配置错误、或者部署流程缺失导致的。

共享主机标准Laravel Inertia部署流程 #

• 修正站点根目录指向：共享主机默认站点根目录一般为public_html，你需要将其调整为Laravel项目的public文件夹。如果你的主机服务商不支持自定义根目录，就把public下的所有文件移动到public_html，同时修改public_html/index.php内的路径引用，指向你存放Laravel核心代码的上层目录即可。
• 完成项目构建与缓存配置：
  1. 本地开发端先执行npm run build打包前端静态资源，将生成的public/build文件夹完整上传到服务器对应路径
  2. 服务器端执行php artisan route:cache、php artisan config:cache、php artisan view:cache生成运行时缓存
  3. 核对.env配置项：APP_ENV设为production、APP_DEBUG设为false、APP_URL填写站点实际访问域名
• 验证运行环境：确保服务器PHP版本与开发环境版本一致，且已安装bcmath、ctype、fileinfo、json、mbstring、openssl、pdo、tokenizer、xml等Laravel和Inertia依赖的扩展
• 配置目录权限：给storage和bootstrap/cache目录设置755权限，保证Web服务器进程有读写权限

@routes报错专项排查 #

完成上述部署步骤后问题仍存在的话，按以下顺序排查：

• 核对入口模板：确认resources/views/app.blade.php内的@routes指令书写正确，无多余转义字符、前后无多余空格
• 确认Ziggy包安装正常：@routes是tightenco/ziggy包提供的Blade指令，未安装该包或者包未正确注册都会导致指令不解析，执行composer require tightenco/ziggy重新安装后清理缓存测试
• 清理所有残留缓存：执行php artisan optimize:clear清空所有缓存后再重新生成运行缓存，排除旧编译模板残留的影响

内容的提问来源于stack exchange，提问作者jp.palubs