Vite 项目在 Hostinger 上部署失败怎么办？原因排查与完整解决方案

Vite 凭借极快的冷启动和热更新速度，已经成为前端项目的主流构建工具。但不少人在本地开发一切正常，把项目搬到 Hostinger 虚拟主机上时却状况百出：打包上传后页面一片空白、控制台里全是资源加载失败的红色报错、点进子路由刷新一下就直接 404。这些问题看起来五花八门，其实根源大多集中在三个地方：构建产物的路径配置、上传的目录位置、以及服务器对单页应用路由的支持方式。本文把常见故障逐一拆解，给出可以直接照抄的配置方案。

一、页面空白与资源 404：base 路径配置是第一嫌疑

部署失败最常见的表现是页面打开后一片空白，打开浏览器开发者工具的 Network 面板，能看到 CSS 和 JS 文件全部返回 404。这几乎可以断定是 Vite 的 base 配置出了问题。Vite 默认以根路径 / 作为资源引用前缀，打包后的 index.html 中资源链接会指向 /assets/xxx.js 这样的绝对路径。Hostinger 虚拟主机的网站根目录是 public_html，如果你的项目是部署在主域名下，这个默认配置没问题；但如果部署在子目录或者临时预览域名上，路径就对不上了。

先打开 vite.config.js 检查 base 选项。部署到子目录时，base 必须写成对应的子目录名，并且前后都要带斜杠：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  // 部署到主域名根路径时用 '/'
  // 部署到 https://你的域名/blog 子目录时必须写成 '/blog/'
  base: '/blog/',
  plugins: [vue()],
  build: {
    outDir: 'dist',
    assetsDir: 'assets'
  }
})

修改完配置后，务必重新执行 npm run build，然后把新生成的 dist 目录内容上传。很多人改了配置却忘记重新打包，或者上传的是旧文件，排查半天方向就错了。上传时还有一个细节容易忽略：要把 dist 目录里面的内容上传到 public_html，而不是把 dist 这个文件夹整个丢进去。如果上传成了 public_html/dist/index.html，访问域名时服务器找不到入口文件，同样会报错。

验证方法很简单，直接在浏览器查看页面源代码，检查资源引用是不是指向了正确的路径。如果源码里的 script 标签指向了不存在的前缀，说明 base 没生效，回去检查配置文件是否保存、构建是否重新执行。

二、路由刷新 404：给 SPA 配置 .htaccess 重写规则

第二个高频问题是：首页能正常打开，页面内点击跳转也正常，但一旦在子路由页面按 F5 刷新，或者直接把子路由链接发给别人打开，Hostinger 就返回 404 页面。这不是 bug，而是单页应用的工作机制与服务器行为的冲突。Vue Router 或 React Router 使用 History 模式时，路由完全由前端 JS 控制，服务器上根本不存在 /about、/user/123 这些物理目录。刷新时浏览器把这些路径原样发给服务器，Apache 找不到对应文件自然返回 404。

解决办法是告诉 Apache：凡是找不到的真实文件或目录，一律回退到 index.html，让前端路由接管。Hostinger 虚拟主机默认使用 Apache，支持 .htaccess 文件。在 public_html 目录下创建一个名为 .htaccess 的文件（注意前面有个点，且没有后缀名），写入以下内容：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  # 如果请求的是真实存在的文件或目录，直接放行
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  # 其余请求全部交给 index.html 处理
  RewriteRule . /index.html [L]
</IfModule>

保存后立即刷新测试，一般就能解决。如果仍然 404，进入 Hostinger 的 hPanel 面板，检查 Advanced 部分的 PHP 配置或联系客服确认 mod_rewrite 模块已启用，不过 Hostinger 主机默认都是开启的。另外提醒一点，如果项目部署在子目录，RewriteRule 里的路径要相应调整为 /子目录名/index.html，RewriteBase 也保持一致。

如果你不需要 URL 中带井号的妥协方案，也可以把路由模式改成 hash 模式，URL 会变成 /#/about 的形式，刷新不会请求服务器路径，自然就不会 404。但 hash 模式的 URL 不够美观，也不利于 SEO，正式项目还是推荐配合 .htaccess 使用 History 模式。

三、构建阶段就失败：Node 版本与依赖问题处理

前面两种情况是部署后的表现，还有一种更早的失败：在本地执行 npm run build 时就直接报错，根本生成不了 dist 目录。Vite 5 要求 Node.js 版本不低于 18，Vite 6 要求 20 以上，如果你本机还装着 Node 16 甚至更老的版本，构建时会直接抛出不兼容的错误提示。先在终端执行 node -v 确认版本，过低就去官方站点下载 LTS 版本重新安装。

另一个常见的构建报错是依赖损坏或版本冲突，典型表现是报 ERR_MODULE_NOT_FOUND 或者某个插件的语法错误。处理思路是删掉 node_modules 目录和 package-lock.json，再重新安装：

rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build

这里需要澄清一个容易混淆的概念：Hostinger 虚拟主机上并不需要安装 Node.js 来运行 Vite 项目。Vite 是构建工具，打包产物是纯静态的 HTML、CSS 和 JS 文件，Apache 直接就能伺服，浏览器端运行。Node.js 只在你本地执行构建命令时需要。如果你购买的是 Hostinger 的 VPS，倒是可以用 Node 环境配合 Nginx 反向代理来跑 SSR 项目，但那是另一套部署方案，和虚拟主机上传静态文件的方式完全不同。

四、部署后的收尾检查清单

按前面的步骤处理完，建议再过一遍这份清单，确认没有遗漏。检查 HTTPS 是否开启，在 hPanel 的 Security 部分启用免费 SSL 证书，并确认页面内没有残留的 http 硬编码资源引用，否则浏览器会拦截混合内容。检查 index.html 是否在 public_html 根位置，assets 文件夹里的文件是否完整上传，文件管理器上传大量小文件时偶尔会漏传或传输不完整，可以用 File Manager 的压缩包上传方式：本地把 dist 内容打成 zip，上传后在线解压，速度快也不容易出错。

最后处理缓存问题。改版上线后部分用户可能看到旧页面，可以在 Hostinger 缓存管理里手动清除缓存，或者在 .htaccess 里针对 index.html 禁用缓存、对带哈希的静态资源设置长缓存，这样既保证更新及时，又利用浏览器缓存提升加载速度。按照这套流程走下来，Vite 项目在 Hostinger 上就能稳定运行了。

Vite部署Hostinger主机前端项目上线修改时间：2026-09-15 13:26:39