如何在 Hostinger 上正确部署 Vite 构建的 Laravel 应用

本文详解在 Hostinger 等共享主机环境部署 vite + laravel 项目的关键步骤：必须执行 npm run build 生成生产就绪的静态资源，并将 public/ 目录完整上传，而非依赖开发服务器。

本文详解在 hostinger 等共享主机环境部署 vite + laravel 项目的关键步骤：必须执行 `npm run build` 生成生产就绪的静态资源，并将 `public/` 目录完整上传，而非依赖开发服务器。

Vite 是一个现代化前端构建工具，但在共享主机（如 Hostinger）上无法运行 Node.js 开发服务器（npm run dev），因此绝不能尝试在 Hostinger 上启动 Vite 的开发服务——这类环境不支持长期运行的进程、websocket 或自定义端口监听。Hostinger 仅提供 PHP + apache/nginx 静态文件托管能力，所有前端资源必须预先构建为纯静态文件。

核心原理在于 Laravel 的 @vite Blade 指令：它并非实时调用 Vite 服务器，而是读取 public/build/manifest.json 文件，从中解析经哈希命名的 JS/CSS 资源路径（例如 assets/app.3f2a1b4e.js），再注入到 HTML 中。该 manifest 文件仅在执行 npm run build（或 vite build）后生成，开发模式（npm run dev）下并不存在。

✅ 正确部署流程如下：

1. 本地完成构建
   在项目根目录运行：

   npm run build # 或使用 pnpm/yarn（若已配置） # pnpm run build # yarn build

   ✅ 成功后，你将在 public/build/ 下看到 manifest.json 及带哈希的资产文件（如 assets/index.xxxxxxxx.js）。

2. 确保 Laravel 配置兼容 Vite 生产模式
   检查 vite.config.js 是否已正确设置 build.outDir（默认即 public/build）：

   // vite.config.js export default defineConfig({   build: {     outDir: 'public/build', // ✅ 必须与 Laravel @vite 默认路径一致   },   // 其他配置... })

3. 上传完整 public/ 目录至 Hostinger

   • 使用 FTP/cPanel 文件管理器，将整个 public/ 文件夹（含 index.php、build/ 子目录及所有生成的静态资源）覆盖上传至 Hostinger 的网站根目录（通常是 public_html/ 或子域名对应目录）。
   • ⚠️ 注意：不要遗漏 public/build/manifest.json —— 缺失它会导致 @vite 指令报错“Unable to locate manifest file”。

4. 验证 Blade 模板用法
   在 resources/views/layouts/app.blade.php 等模板中，确保使用标准 @vite 语法：

   @vite(['resources/css/app.css', 'resources/js/app.js'])

   Laravel 会自动根据 manifest.json 映射到最终带哈希的路径，实现缓存失效控制。

? 补充说明：

• Hostinger 不支持 .env 中设置 VITE_DEV_SERVER_URL 或启用 HMR；这些仅适用于本地开发。
• 若你误传了 dev 模式下的 public/（无 build/ 目录），页面将白屏或报 404 —— 因为 @vite 找不到 manifest 并回退失败。
• 建议在 package.json 的 build 脚本中加入清理步骤，避免残留旧文件：

  "scripts": {   "build": "rm -rf public/build && vite build" }

  （windows 用户可替换为 rimraf public/build && vite build，需先 npm install rimraf –save-dev）

总结：Hostinger 部署 Vite 的本质是「静态化交付」——把 Vite 编译结果当作普通静态资源交给 PHP 服务托管。牢记口诀：本地构建，上传 public，依赖 manifest，放弃 dev server。