Vue 静态托管

部署你的
Vue 项目

上传 Vue、Vite、Vue CLI 或 Nuxt 的静态输出，发布时保留 history mode 回退、HTTPS、全球边缘网络，以及需要时可接的自定义域名。

查看设置步骤
vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
plugins: [vue()],
// Use a deploy-safe asset base
base: './',
build: {
outDir: 'dist'
}
})
Vite 与 webpack 可用

先搞清楚要上传哪个 Vue 文件夹

多数 Vue 部署问题在托管前就发生：上传错输出文件夹、base path 错误，或 build 没有先本机预览。

Vite + Vue

npm run build
output: dist/

Vite 默认把正式构建结果放在 dist。如果 config 修改了 build.outDir 或 base，请上传实际输出文件夹并测试资源 URL。

Vue CLI

npm run build
output: dist/

Vue CLI 静态 build 通常部署 dist。如果 app 会放在子路径，publicPath 需要符合最后 URL 结构。

Nuxt static output

nuxi generate
output: .output/public or dist/

Nuxt 可以生成静态输出，但 server-rendered routes 和 server APIs 需要 runtime。这个流程只上传生成后的 public 静态文件。

Vue Router history mode 真正需要什么

干净 URL 值得保留

Hash routes 几乎哪里都能跑，但带 # 的网址看起来像 workaround，分享链接和访问统计都会显得不够干净。

Vue Router history mode 让你使用 /about 或 /dashboard/settings 这类干净路径。代价是主机必须知道：不是实际文件的路由，要回到 index.html。

DeployPages 如何处理 history mode

当请求没有对应真实静态资源时，DeployPages 会提供根目录 index.html，让 Vue Router 在浏览器中解析最后画面。

  • 直接访问嵌套路由不会立刻硬失败。
  • 根目录 index.html 会作为回退响应。
  • Vue mount 后读取当前 URL，渲染正确路由。

Vue 上线前检查

Vue app 在 dev 正常，仍可能上传后失效。这些检查能先抓出常见问题。

Base path

Vite 请确认 base；Vue CLI 请确认 publicPath。错误值通常会变成 CSS、JS、字体或图片 404。

History 回退

直接打开嵌套路由并刷新。如果页面仍正常，就表示回退设置生效。

纯静态输出

DeployPages 提供静态文件。API routes、server middleware 和 SSR-only 行为需要独立后端或 runtime。

本机预览

请用真正的本机 preview server 检查正式构建结果。用 file:// 开 dist/index.html 可能会隐藏或制造与部署不同的问题。

Vue 部署流程

01

构建静态资源

在 Vite、Vue CLI 或 Nuxt static mode 执行正式构建，让 app 生成浏览器可直接加载的文件。

02

找到输出文件夹

多数 Vue 和 Vite 项目输出到 dist。Nuxt static 项目则依设置上传 .output/public 或生成后的 dist。

Nuxt static build 通常依项目设置上传 .output/public 或 dist。

03

上传并验证链接

上传完整输出文件夹，网站上线后检查深层链接、router 导航和资源路径。

常见 Vue 部署问题

Fix 01

嵌套路由刷新回 404

Vue Router 使用 history mode，但托管服务正在找真实文件。使用 SPA 回退，让未知 document route 回到 index.html。

Fix 02

CSS 或 JS 文件回 404

检查 Vite base 或 Vue CLI publicPath，也确认你上传了完整 dist 文件夹，包含生成后的 assets。

Fix 03

Hash mode 可用，history mode 不行

Hash mode 把路由放在浏览器 # 之后。History mode 使用干净 URL，因此直接访问时需要服务器回退行为。

Fix 04

Nuxt 输出缺少服务器行为

Static Nuxt output 可以用文件托管。Nuxt server routes、server middleware 和 SSR-only 行为需要 server runtime。

Vue 部署常见问题

为什么 CSS 和 JS 文件回 404？

这通常代表资源路径是用另一个 base URL 构建，或 assets 目录没有上传。Vite 请看 base，Vue CLI 请看 publicPath。

支持 Nuxt 吗？

支持静态输出。请先生成静态网站，再上传生成的 public 文件夹。DeployPages 不适合 Nuxt server rendering 或 server API routes。

应该用 hash mode 还是 history mode？

想要干净 URL 且主机支持回退到 index.html，就用 history mode。Hash mode 较容易托管，但每个 client-side route 都会有 #。

应该上传 Vue 原始项目吗？

不用。请上传正式输出文件夹，通常是 dist。原始项目包含开发文件和依赖包，不适合直接提供。

Pinia 或 Vuex 状态刷新后会保留吗？

不会自动保留。浏览器刷新会重置内存中的 client state。重要状态请用 localStorage 或你偏好的 persistence plugin。

可以回滚到上一个版本吗？

可以。DeployPages 保留部署历史，需要时可以回到先前的静态 build。