企业官网建设流程全解析

“vue3+vite单页面改多页面”这个标题，看着就是一个非常典型的工程化改造需求。我最初接手这类任务时也以为只是改个构建配置，实际上手才发现，牵涉到目录结构、路由方案、公共模块复用、部署路径等一系列问题。这篇文章就从我实际改造的经验出发，把完整思路和踩过的坑都写清楚，给准备动手或正在改造的同学一份能直接抄作业的参考。

先说结论：Vite 做多页面（MPA）的支持远比 webpack 时代要优雅，核心只需要在build.rollupOptions.input里配置多个 HTML 入口，但工程上的配套改造才是重头戏。下面逐步拆解。

1. 为什么要把单页面改造成多页面

1.1 什么场景下会出现这种需求

很多 Vue 项目初期都是用npm create vite@latest直接拉的模板，默认就是单页面应用（SPA），入口只有一个index.html，所有页面靠 vue-router 在浏览器端切换。这种模式在大部分业务下没问题，但实际项目做着做着就会出现几类需求：

第一类是后台管理系统要拆子系统。比如我接触过一个运营平台，刚开始只有一个后台，后来数据看板和用户管理两个模块的上线节奏完全不一致，两个团队分别维护，再共用一套 SPA 路由和一套构建产物就很别扭。每次发布都要一起上线，风险被强行绑定。

第二类是同一套代码要输出多个独立的落地页、活动页或 H5 页面。这些页面之间没有顶层导航关系，用户从不同渠道进入，需要各自独立的 HTML 入口，方便运营单独投放、单独统计。

第三类是某些页面对首屏加载速度有硬性要求。SPA 不管路由怎么懒加载，入口 HTML 始终是同一个，所有页面的运行时脚本都挤在一个 bundle 体系里。MPA 天然按页面拆分产物，互不干扰，首屏只加载当前页面需要的资源，性能隔离更干净。

1.2 多页面方案的核心价值与取舍

改造成多页面后，最直观的好处有三个：

• 每个页面有独立入口 HTML，可以各自设置 title、meta、favicon，甚至引入不同的第三方脚本。
• 构建产物按页面目录拆分，互不依赖，部署时可以单独发布某个页面。
• 公共依赖如果拆包合理，多个页面之间可以共享浏览器缓存，访问过 A 页面的用户再访问 B 页面时，公共 chunk 直接命中缓存。

但代价也很明显：页面之间跳转需要整页刷新，不再有 SPA 那种“无刷新切换”的流畅感。如果业务本身是一个连贯的、模块间频繁跳转的强交互应用，改成 MPA 反而会变慢。所以开干之前一定要和业务确认清楚，不要为了技术上的“标准”而牺牲使用体验。

1.3 改造前的三个核心问题

正式动手前，我建议你先重新审视下面三件事，它们决定改造方案的形态：

1. 页面边界怎么划。哪些功能算一个独立页面？判断标准是上线节奏、维护团队、入口来源，而非功能菜单的层级。菜单里的二级页面通常不该拆成独立入口。
2. 公共代码放哪里。登录态、请求封装、公共组件、工具函数是每个页面都要用的，这部分要抽成公共目录，但要注意别把页面特有的路由配置也塞进公共目录。
3. 部署路径怎么定。是根路径部署，还是子路径部署？这直接影响 Vite 的base配置和前端路由的base参数。这块不先想明白，后面构建出的资源路径大概率会踩坑。

2. 改造前的目录重构与入口规划

2.1 推荐的多页面目录结构

Vite 官方文档对 MPA 的推荐做法是配置多个 HTML 入口。但在真实项目中，HTML 文件放哪里、脚本和页面代码怎么组织，直接决定后续好不好维护。

我改造后最终采用的目录结构是这样的：

├── src │ ├── common │ │ ├── api │ │ ├── components │ │ ├── hooks │ │ └── utils │ ├── pages │ │ ├── home │ │ │ ├── index.html │ │ │ ├── main.js │ │ │ ├── App.vue │ │ │ └── router │ │ │ └── index.js │ │ └── admin │ │ ├── index.html │ │ ├── main.js │ │ ├── App.vue │ │ └── router │ │ └── index.js ├── vite.config.js └── package.json

每个页面目录都是一个“迷你 Vue 应用”，有自己的 HTML、入口脚本、根组件和路由。src/common放跨页面共享的代码。这样做的直观好处是：新接一个页面的成本非常低，复制一个目录改一下入口配置就能跑起来。

2.2 独立入口 HTML 的放置方案对比

HTML 文件的放置位置，我见过两种做法：

第一种是把所有 HTML 都放在项目根目录，比如根目录下的home.html、admin.html，Vite 配置里直接引用这些文件。优点是最贴近官方文档的写法，缺点是一旦页面多起来，根目录会被 HTML 文件堆满，而且 HTML 和它的入口脚本距离很远，改起来要多跳几层目录。

第二种就是我上面用的方案，HTML 放在各自页面目录下，与页面代码内聚。Vite 配置里指向src/pages/home/index.html即可。这种方式在工程上更清晰，我强烈推荐。有一个细节要注意：HTML 里引入口脚本时，尽量使用相对路径./main.js，而不是以/src/pages/home/main.js开头的根路径写法。相对路径在 dev 和 build 下都不容易出问题，后面调整base时也更省心。

2.3 公共模块与业务模块的边界划分

改造过程中最容易犯的错，是把公共模块当成“垃圾桶”。我在实际操作中的划分标准很简单：如果一段代码会被两个及以上页面引用，才放进src/common；否则就留在页面目录内部。

比如 axios 实例封装、用户登录信息存取、通用 UI 组件、日期格式化这类工具，属于典型的公共模块。但某个页面独有的接口请求、某个业务域的表格组件，就应该留在对应页面目录里。这样划分后，构建时不会出现页面 A 的代码被打包进页面 B 的产物这种尴尬情况。

另外建议在vite.config.js里配置好@别名指向src目录，并顺手配置@common指向src/common：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import { resolve } from 'path' export default defineConfig({ resolve: { alias: { '@': resolve(__dirname, 'src'), '@common': resolve(__dirname, 'src/common') } }, plugins: [vue()] })

这里有个 ESM 环境的坑：如果package.json里设置了"type": "module"，vite.config.js里直接使用__dirname会报错，需要改用fileURLToPath(new URL('./src', import.meta.url))来转换。顺手避坑，别等报错再查。

3. Vite 配置多入口：从 dev 到 build

3.1 核心配置说明

多页面改造最核心的就是build.rollupOptions.input。这个配置告诉 Vite 构建时要把哪些 HTML 作为入口分别打包。我改造后的配置如下：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import { resolve } from 'path' export default defineConfig({ resolve: { alias: { '@': resolve(__dirname, 'src'), '@common': resolve(__dirname, 'src/common') } }, build: { rollupOptions: { input: { home: resolve(__dirname, 'src/pages/home/index.html'), admin: resolve(__dirname, 'src/pages/admin/index.html') } } }, plugins: [vue()] })

input 对象里的 key（home、admin）会直接决定构建产物的文件名。比如home对应的入口构建后会在dist目录生成home.html，而不是默认的index.html。如果你希望部署后用户直接访问域名根路径就打开某个页面，可以把这个页面的 key 设置为index，构建生成index.html。我实际项目中通常保留一个index入口作为默认落地页，其余页面按功能命名。

如果后续新增页面，只需要在 input 里加一行，同时在src/pages下新建对应的目录结构，两步就能完成一个页面的接入。

3.2 dev server 如何访问多页面

配置完 input 后，很多人第一反应是执行npm run dev，然后访问http://localhost:5173/，发现页面白屏或者 404。这不是配置错了，而是 dev server 默认展示根目录下的index.html，而你的入口 HTML 现在散落在各个页面目录里。

多页面下 dev 环境正确的访问方式是带路径访问：http://localhost:5173/src/pages/home/index.html。这样确实有些难看，而且每次都要手打长路径。

更优雅的做法是在 Vite 配置里加一个自定义中间件，把根路径重定向到固定入口：

export default defineConfig({ plugins: [ vue(), { name: 'mpa-redirect', configureServer(server) { server.middlewares.use((req, res, next) => { if (req.url === '/') { res.statusCode = 302 res.setHeader('Location', '/src/pages/home/index.html') res.end() return } next() }) } } ] })

这样开发时访问根路径就会自动跳到 home 页面，体验和单页面应用没有差别。额外提醒一点：server.open配置这时候也要写成具体的页面路径，比如server: { open: '/src/pages/home/index.html' }，否则自动打开浏览器时还是会 404。

3.3 base 路径与静态资源处理

base是 Vite 里一个非常关键但又容易被忽略的配置。它的作用是给构建后的 HTML 中引用的 JS、CSS、图片等资源统一加路径前缀。

如果你的项目要部署在域名根路径（比如https://example.com/），base保持默认的'/'即可，构建后的资源路径是/assets/xxx.js。如果部署在子路径（比如https://example.com/admin/），就必须设置base: '/admin/'，否则资源路径会变成/assets/xxx.js，请求打到域名根路径下，直接 404。

多页面 + 子路径部署还有一个特殊坑：每个页面可能部署在不同的子路径下。比如 home 页面在根路径部署，admin 页面在/admin/下部署。这种场景下，一个 Vite 全局base无法满足两个页面的不同需求。

我的处理方案是分开构建。用环境变量区分部署场景，加载不同的base：

export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd(), '') return { base: env.VITE_BASE || '/', // 其他配置 } })

然后准备两套.env文件，.env.home里设置VITE_BASE=/，.env.admin里设置VITE_BASE=/admin/。构建时执行vite build --mode admin，admin 页面的资源路径就会自动带上/admin/前缀。这里确实要提前规划好部署方案，否则后面返工成本很高。

3.4 按需构建指定页面

多页面项目还有一个非常实用的进阶配置：按需构建。比如你只想单独打包 admin 页面，而不想每次发布都把所有页面构建一遍。结合热词里提到的vite build --mode test，我们可以用 mode 和 loadEnv 实现这个需求。

具体做法是在.env.test中配置要构建的页面列表：

VITE_BUILD_PAGES=admin

然后在vite.config.js中用loadEnv读取，动态生成 input：

import { defineConfig, loadEnv } from 'vite' import vue from '@vitejs/plugin-vue' import { resolve } from 'path' export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd(), '') const allPages = { home: resolve(__dirname, 'src/pages/home/index.html'), admin: resolve(__dirname, 'src/pages/admin/index.html') } let input = allPages if (env.VITE_BUILD_PAGES) { const pageNames = env.VITE_BUILD_PAGES.split(',') input = pageNames.reduce((acc, name) => { if (allPages[name]) { acc[name] = allPages[name] } return acc }, {}) } return { base: env.VITE_BASE || '/', build: { rollupOptions: { input } }, plugins: [vue()] } })

执行vite build --mode test时，只会构建 admin 页面。对于几十个入口的大型项目，这个配置能显著缩短发布耗时。我的建议是把allPages对象单独抽到一个pages.js文件里，维护起来更清晰。

4. 多页面下的代码组织与公共复用

4.1 页面级路由拆分

配置层面搞定后，接下来是业务代码层面的调整。每个页面需要有自己的路由实例，不能再像 SPA 那样把所有路由都集中在根目录的router/index.js里。

我在页面目录下各自维护一份router/index.js，示例：

import { createRouter, createWebHashHistory } from 'vue-router' const routes = [ { path: '/', component: () => import('../views/Dashboard.vue') }, { path: '/list', component: () => import('../views/List.vue') } ] const router = createRouter({ history: createWebHashHistory(), routes }) export default router

这里我推荐用createWebHashHistory而不是createWebHistory。原因比较现实：多页面每个入口都是一个独立应用，如果用 history 模式，用户刷新某个子路由时，服务器必须正确配置回退规则。而多页面本身已经有多套部署路径，再叠加 history 回退规则，nginx 配置会变得复杂且脆弱。hash 模式虽然 URL 里多个#，但在多页面拆分场景下，稳定性和免部署配置的优势非常明显。

如果业务确实要求 history 模式，那么createWebHistory的 base 参数要传对应页面的部署子路径，比如createWebHistory('/admin/')，并且 nginx 要对这个子路径配置try_files回退，下面第 5 章会给出检查清单。

4.2 页面入口脚本与状态初始化

每个入口的main.js大同小异，我在 home 页面的入口脚本长这样：

import { createApp } from 'vue' import { createPinia } from 'pinia' import App from './App.vue' import router from './router' const app = createApp(App) const pinia = createPinia() app.use(pinia) app.use(router) app.mount('#app')

这里特别提醒一个多页面场景下的状态管理问题：每个页面都是独立的应用实例，所以每个入口里都要createPinia()，不能像 SPA 那样全局共享一个 store。如果你在页面之间使用了 localStorage 或 sessionStorage 做登录态持久化，还需要在入口脚本里显式初始化并校验用户状态。

我实际踩过的一个坑是：改造前 SPA 里有一个全局的userStore，登录后存在内存里，路由跳转也能拿到。改造后 A 页面和 B 页面各是一个应用，内存中的状态完全不互通，刷新后 store 直接空了。最后统一改为从 localStorage 读取并校验 token，在各自入口的main.js里完成初始化，问题才解决。

4.3 公共复用策略与构建踩包优化

在改造前，SPA 里公用的组件和工具函数大概率分布在各层目录中。改造后我建议统一收敛到src/common下，并且只保留真正跨页面复用的代码。但是更重要的，是公共代码在构建时容易重复打包的问题。

我用一个具体数字说明：没配置拆包前，home 和 admin 两个页面构建产物里，各自都包含了一份完整的 Vue 运行时。两个页面加起来，Vue 相关代码被打了两次，整体体积增加了将近 120KB。这是因为每个入口都是独立的 Rollup 入口，公共依赖默认跟随入口各自打包。

解决办法是用manualChunks把第三方依赖单独拆出来：

build: { rollupOptions: { output: { manualChunks(id) { if (id.includes('node_modules')) { if (id.includes('vue') || id.includes('pinia') || id.includes('vue-router')) { return 'vue-vendor' } if (id.includes('echarts') || id.includes('lodash')) { return 'utils-vendor' } return 'vendor' } } } } }

配置后，home 和 admin 页面共享的第三方库会被抽取成公共 chunk，浏览器第一次访问某个页面后，第二个页面就能命中缓存。这个配置在页面数量增多后收益很大，建议在改造一开始就加上。

这里也要留个心眼：manualChunks不是拆得越细越好。拆分粒度过小会导致很多小文件，HTTP 请求数增多，反而影响加载性能。我的经验是，把 Vue 生态单独拆一个，把体积较大的可视化库、工具库拆一个，业务代码保持跟随页面构建即可。

4.4 页面级 HTML 的标题与 SEO 处理

多页面相比 SPA 还有一个附带红利：每个页面可以独立设置 HTML 的 title、description、keywords，不需要依赖document.title这种运行时手段。

我在每个页面的index.html里直接写死对应页面的内容：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="description" content="运营数据看板 - 实时掌握业务核心指标" /> <title>数据看板</title> </head> <body> <div id="app"></div> <script type="module" src="./main.js"></script> </body> </html>

如果页面是面向用户的落地页，这种静态 SEO 信息比 SPA 的运行时注入更友好，爬虫直接读取 HTML 就能拿到主要内容描述。这是改造成 MPA 后几乎零成本的收益，顺手就做了。

5. 构建优化与踩坑排查实录

5.1 常见报错与解决办法速查表

改造过程中我整理了一批高频问题，很多都是多人团队里反复被问到的，直接列一个表格，方便对症状查问题：

5.2 Windows 环境下的 NODE_OPTIONS 命令坑

热词里能看到一串$ node_options=--max-old-space-size=4096 vite，并且后面跟着 “'node_options' 不是内部或外部命令” 这种报错。这个我在 Windows 环境下也遇到过。

问题出在 Windows 的 cmd 和 PowerShell 不认 Linux 风格的VAR=value command写法。命令行直接设置环境变量，Windows 要用set：

set NODE_OPTIONS=--max-old-space-size=4096 vite build

但这样每次都要手动敲，而且容易忘记。更好的方案是在package.json里用cross-env统一处理：

{ "scripts": { "build:home": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vite build --mode home", "build:admin": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vite build --mode admin" } }

注意：环境变量名必须大写NODE_OPTIONS，同时--max-old-space-size=4096表示将 Node 的堆内存上限提升到 4GB。多页面项目入口多、依赖多时，构建进程出现JavaScript heap out of memory的概率明显高于单页面，提前把这个配置加进构建脚本，能省去不少线上构建失败后排查的焦虑。

5.3 构建体积与缓存策略

多页面改造完成后，我建议在dist产物目录下核对一下各页面 HTML 的大小和资源引用路径。正常情况下，每个页面的 HTML 应该只有几 KB，里面的 JS 路径指向assets目录下带 hash 的文件。

Vite 默认对 JS 和 CSS 文件名加了内容 hash，这是静态资源长效缓存的基石。每次发布，只有内容变化的文件 hash 会变，未变化的部分能继续命中浏览器缓存。不要手动关掉这个行为，除非你有极强的理由。

对于公共 chunk，还可以在服务器端设置更长的缓存时间。比如 Vue 运行时这类极少变动的文件，nginx 里可以缓存一年：

location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; }

但要注意：HTML 文件本身不要设置长缓存。因为 HTML 里引用的资源路径带有 hash，如果用户命中了旧 HTML，就还会去请求旧资源，导致发布后用户看到旧版本。建议 HTML 设置no-cache，让浏览器每次回源校验。

5.4 上线部署的检查步骤

最后是部署环节。多页面项目部署前，我一般按以下清单逐项检查，避免线上翻车：

1. 确认base是否匹配部署路径。子路径部署时，页面上的静态资源请求路径前缀应该与部署目录一致。
2. 确认 nginx 静态文件 root 指向构建产物目录。比如构建产物在dist，根目录部署时root /var/www/dist;，子路径部署时location /admin/ { alias /var/www/dist/; }。
3. 确认路由模式。hash 模式无需额外配置；history 模式需要在对应 location 里配置try_files $uri $uri/ /admin/index.html;，注意这里不能直接写根路径的 index.html。
4. 确认接口代理是否生效。如果 dev 环境用 Vite 的 proxy 代理了/api，线上也要在 nginx 里配置对应的proxy_pass，否则所有接口请求都会打到静态资源服务器上。
5. 确认各入口 HTML 的 title、meta 符合预期，打开页面后逐个抽查。开发环境和构建环境的base不同时，尤其要注意构建后的资源引用路径。

这一套检查下来，基本能覆盖多页面部署的绝大多数问题。

6. 我的几点体会

多页面改造这件事，配置本身并不复杂，真正的复杂度在工程结构设计和历史代码的合规性改造上。我从单体 SPA 改动到三入口 MPA，前期最花时间的不是写 Vite 配置，而是梳理哪些代码是页面私有的、哪些是公共的，以及登录态怎么跨页面保持。如果你也是从既有项目改造，建议先做代码结构梳理，再动vite.config.js，顺序反了会不断返工。

最后分享一个小技巧：改造时可以先用一个最简单的页面（比如一个登录页）走通 MPA 全链路，确认 dev、build、部署都正常后，再批量迁移其他页面。不要一次性把全部页面迁完再验证，问题范围会大到你不想面对。