企业官网建设流程全解析

简介：本资源是一套面向前端初学者与Vue 2开发者进阶Vue 3的系统化学习材料，聚焦Composition API、响应式原理、组件通信、路由与状态管理等核心能力培养，助力快速构建现代化单页应用。压缩包共120个文件，含43个HTML示例页（覆盖过渡动画、表单绑定、列表渲染等基础实践）、33个Vue组件文件（体现选项式与组合式写法对比）、16个JS逻辑脚本（含Pinia状态管理与自定义Hook封装），辅以SCSS样式、JSON配置及项目工程配置文件（如vite.config.js隐含于browserslistrc等），整体仅807KB，轻量易导入。已有230人下载学习，内容结构由浅入深：从响应式机制解析起步，经组件开发规范训练，最终落地完整实战项目，配套代码即开即用，目录模块清晰，关键知识点均配有可运行示例与注释说明，适合边学边练、查缺补漏。

1. 为什么现在学 Vue3，不能只看“入门”两个字就点开视频？

很多刚点开“Vue3 入门与实战.zip”的人，第一反应是：装完 Node、跑通create-vue、写个ref和setup，就算入了门。但真实项目里，你马上会遇到：路由跳转后页面空白、v-model在自定义组件里失效、computed依赖没更新、打包后静态资源路径错乱、甚至在 Edge 浏览器里window.close()被拦截——这些都不是语法错误，而是 Vue3 运行时机制、构建链路和浏览器兼容性共同作用的结果。本篇不讲“什么是响应式”，而是聚焦一个工程师真正动手时的断点：从初始化一个可调试、可部署、可协作的 Vue3 项目开始，把vite create-vue生成的脚手架，变成能接入真实 API、支持多环境配置、带源码映射调试能力、且能在 Windows Server + Nginx 环境稳定运行的最小生产基线。适合已会写基础 HTML/JS、正准备接手 Vue3 后台管理系统或 H5 项目的前端开发者，也适合 Java/SpringBoot 后端想快速补齐前端交付能力的工程师。

2. 用create-vue搭建可调试、可部署的 Vue3 最小基线

Vue3 官方推荐的初始化方式早已从vue-cli切换为基于 Vite 的create-vue。它不是简单模板，而是一套可演进的工程骨架。关键不在“创建”，而在“创建后立刻验证是否具备调试与部署能力”。

2.1 执行初始化并验证开发服务器可调试

npm create vue@latest # 交互式选择： # ✔ Project name: … my-vue3-app # ✔ Add TypeScript? … No / Yes（建议选 Yes，后续排查类型问题成本远低于 runtime 错误） # ✔ Add JSX Support? … No（除非明确需 JSX 写法，否则组合式 API + `<script setup>` 更主流） # ✔ Add Vue Router for Single Page Application routing? … Yes（90% 后台系统需要） # ✔ Add Pinia for state management? … Yes（Vue3 官方状态库，替代 Vuex） # ✔ Add Vitest for Unit Testing? … No（入门阶段可跳过，但上线前必须补） # ✔ Add Cypress for both Unit and End-to-End testing? … No # ✔ Add ESLint for code quality? … Yes（强制代码规范，避免团队协作踩坑） # ✔ Add Prettier for code formatting? … Yes

执行完成后，进入项目并启动：

cd my-vue3-app npm install npm run dev

提示：若启动后浏览器打开空白页且控制台报Failed to resolve import "./App.vue"，大概率是vite版本与create-vue模板不匹配。此时不要降级 vite，而应直接升级模板：npm create vue@latest -- --overwrite覆盖重装。Vite 5.x 与 Vue3.4+ 组合对defineAsyncComponent和SSR支持更稳，旧模板可能仍用 Vite 4.x。

验证调试能力的关键动作：
在src/App.vue中添加一行console.log('App mounted')，保存后观察浏览器控制台是否立即输出；再修改<template>中任意文本，确认热更新（HMR）是否秒级生效。若 HMR 失效，检查vite.config.ts中server.hmr是否被误设为false（默认为true）。

2.2 配置多环境变量，让开发、测试、生产请求不同 API 地址

Vue3 项目默认只读取.env文件，但实际部署需区分环境。Vite 支持按模式加载变量，需手动建立三类文件：

# .env.development（仅开发时加载） VUE_APP_API_BASE_URL=http://localhost:8080/api # .env.staging（测试环境） VUE_APP_API_BASE_URL=https://test-api.example.com/api # .env.production（生产环境） VUE_APP_API_BASE_URL=https://api.example.com/api

在vite.config.ts中显式声明变量暴露规则：

// vite.config.ts export default defineConfig({ // ...其他配置 define: { __APP_VERSION__: JSON.stringify(process.env.npm_package_version), }, // 关键：让 VUE_APP_* 变量在运行时可用 envPrefix: ['VUE_APP_', 'NODE_ENV'], })

在代码中使用：

// src/utils/request.ts const baseURL = import.meta.env.VUE_APP_API_BASE_URL || '/api' export const request = axios.create({ baseURL })

注意：Vite 的import.meta.env是编译时注入，不是运行时读取。所有以VUE_APP_开头的变量，在构建时会被静态替换。因此console.log(import.meta.env.VUE_APP_API_BASE_URL)在生产包里会直接显示字符串值，而非变量名。这是安全设计，避免敏感信息泄露。

2.3 生成可部署的静态资源包，并验证 Nginx 路径兼容性

执行构建命令：

npm run build

构建产物默认输出到dist/目录。但直接将dist/丢进 Nginx 根目录常导致路由 404——因为 Vue Router 默认用history模式，依赖浏览器 History API，而 Nginx 不会将/user/list这样的路径转发给index.html。

解决方法：在vite.config.ts中配置base，并同步调整 Nginx：

// vite.config.ts export default defineConfig({ base: './', // 关键：设为相对路径，避免部署到子路径时资源 404 build: { outDir: 'dist', assetsDir: 'assets', } })

Nginx 配置片段（nginx.conf）：

location /my-app/ { alias /var/www/my-app/dist/; try_files $uri $uri/ /my-app/index.html; # 关键：所有未命中文件的请求都 fallback 到 index.html }

提示：若部署在根路径（如https://example.com/），则base: '/'即可，Nginx 配置改为location / { try_files $uri $uri/ /index.html; }。Windows Server 上 Nginx 需确认nginx.conf中worker_processes设为auto，且events块内use指令设为epoll（Linux）或select（Windows），否则高并发下可能卡顿。

3. 实战：用 Vue Router + Pinia 构建带权限控制的后台菜单系统

后台管理系统最典型场景：登录后根据角色动态渲染侧边栏菜单，点击菜单跳转对应页面，且路由守卫校验 token 有效性。这要求 Vue Router 与 Pinia 协同工作，而非各自为政。

3.1 定义动态路由表结构，支持后端返回菜单数据驱动渲染

不硬编码router/index.ts，而是设计可扩展的路由元信息：

// src/router/types.ts export interface MenuItem { id: string title: string path: string icon?: string // 如 'icon-user' component: string // 对应 views 目录下的文件名，如 'UserList.vue' children?: MenuItem[] meta?: { requiresAuth?: boolean permission?: string[] // 如 ['user:read', 'user:edit'] } } // src/router/index.ts import { createRouter, createWebHistory } from 'vue-router' import { useUserStore } from '@/stores/user' // 动态添加路由前，先定义基础路由（登录页、404） const routes = [ { path: '/login', name: 'Login', component: () => import('@/views/Login.vue'), }, { path: '/404', name: 'NotFound', component: () => import('@/views/NotFound.vue'), }, { path: '/', redirect: '/dashboard', }, ] const router = createRouter({ history: createWebHistory(), routes, }) // 全局前置守卫：检查登录状态 & 注入动态路由 router.beforeEach(async (to, from, next) => { const userStore = useUserStore() if (to.meta?.requiresAuth && !userStore.token) { next({ name: 'Login' }) return } // 若已登录但尚未加载菜单，则拉取并 addRoute if (to.meta?.requiresAuth && !userStore.menus.length) { try { await userStore.fetchMenus() // 该 action 会调用 API 获取菜单数据 // 将后端返回的菜单数据转换为 RouteRecordRaw 并 addRoute userStore.menus.forEach(menu => { router.addRoute({ path: menu.path, name: menu.id, component: () => import(`@/views/${menu.component}`), meta: menu.meta, }) }) next({ ...to, replace: true }) // 替换当前导航，避免重复触发 } catch (err) { console.error('Failed to load menus:', err) next({ name: 'NotFound' }) } } else { next() } }) export default router

3.2 在 Pinia Store 中管理用户状态与菜单数据

// src/stores/user.ts import { defineStore } from 'pinia' import { login, getMenus } from '@/api/auth' import type { MenuItem } from '@/router/types' interface UserState { token: string | null userInfo: Record<string, any> menus: MenuItem[] } export const useUserStore = defineStore('user', { state: (): UserState => ({ token: localStorage.getItem('token') || null, userInfo: {}, menus: [], }), actions: { async login(credentials: { username: string; password: string }) { const res = await login(credentials) this.token = res.token localStorage.setItem('token', res.token) this.userInfo = res.user }, async fetchMenus() { if (!this.token) return const res = await getMenus() this.menus = res.data }, logout() { this.token = null this.userInfo = {} this.menus = [] localStorage.removeItem('token') } }, getters: { isLoggedIn(): boolean { return !!this.token } } })

3.3 在 Layout 组件中渲染动态菜单，并处理点击跳转

<!-- src/layouts/SideMenu.vue --> <template> <el-menu :default-active="$route.path" class="side-menu" @select="handleMenuSelect" > <template v-for="menu in userStore.menus" :key="menu.id"> <el-sub-menu v-if="menu.children" :index="menu.path"> <template #title> <el-icon><component :is="menu.icon || 'Document'" /></el-icon> <span>{{ menu.title }}</span> </template> <el-menu-item v-for="child in menu.children" :key="child.id" :index="child.path" > {{ child.title }} </el-menu-item> </el-sub-menu> <el-menu-item v-else :index="menu.path"> <el-icon><component :is="menu.icon || 'Document'" /></el-icon> <template #title>{{ menu.title }}</template> </el-menu-item> </template> </el-menu> </template> <script setup lang="ts"> import { useRouter } from 'vue-router' import { useUserStore } from '@/stores/user' const router = useRouter() const userStore = useUserStore() const handleMenuSelect = (index: string) => { router.push(index) } </script>

注意：el-menu的@select事件传入的是index字符串，即菜单项的path。router.push(index)会触发 Vue Router 导航，进而触发beforeEach守卫校验权限。若用户无权限访问该路径，守卫中next({ name: 'NotFound' })会跳转至 404 页面，无需在菜单层做二次判断。

4. 排查 Vue3 常见运行时问题：从控制台报错到源码定位

Vue3 的响应式系统和编译优化带来性能提升，但也引入新一类错误模式。以下三类问题高频出现，且无法靠 ESLint 提前捕获。

4.1Uncaught ReferenceError: __VUE_SSR_SET_VALUE__ is not defined—— SSR 相关错误的根源定位

该错误通常出现在使用defineAsyncComponent加载组件时，且项目未启用 SSR。根本原因是：Vite 在开发模式下会注入 SSR 相关 polyfill，但某些第三方 UI 库（如部分版本的ant-design-vue）在非 SSR 环境下错误引用了 SSR 工具函数。

验证步骤：

1. 在浏览器控制台执行console.log(typeof __VUE_SSR_SET_VALUE__)，若返回"undefined"，说明该变量确实未声明；
2. 查看报错堆栈，定位到具体哪一行 JS 文件调用了__VUE_SSR_SET_VALUE__；
3. 检查该文件是否来自node_modules/ant-design-vue或类似 UI 库。

解决方案：
升级ant-design-vue至4.1.0+（已移除 SSR 引用），或临时 patch：

// src/main.ts（入口文件顶部） // 临时注入空函数，避免运行时报错（仅用于开发） if (typeof __VUE_SSR_SET_VALUE__ === 'undefined') { (window as any).__VUE_SSR_SET_VALUE__ = () => {} }

提示：此 patch 仅用于快速验证是否为 SSR 兼容问题。长期方案必须升级依赖或向库维护者提交 issue。可通过npm ls ant-design-vue查看实际安装版本。

4.2Computed property "xxx" was assigned to but it has no setter——computed赋值失败的两种真实场景

computed默认只读，但开发者常误以为v-model绑定computed就能双向更新。实际上只有显式声明get和set的computed才可赋值。

场景一：v-model绑定computed但未提供set

// ❌ 错误写法 const searchQuery = computed(() => store.searchQuery) // 模板中：<input v-model="searchQuery" /> // 报错：Cannot assign to read only property 'searchQuery'

修正为：

// ✅ 正确写法：提供 set，同步更新 store const searchQuery = computed({ get() { return store.searchQuery }, set(value) { store.searchQuery = value } })

场景二：computed依赖响应式对象属性，但该对象被整个替换

// ❌ 错误写法 const user = ref({ name: 'Alice', age: 25 }) const fullName = computed(() => user.value.name + ' (' + user.value.age + ')') // 后续执行：user.value = { name: 'Bob', age: 30 } → fullName 不更新！

原因：computed依赖的是user.value的引用，当user.value被重新赋值，原响应式连接断裂。
修正为：使用shallowRef或确保只修改属性：

// ✅ 正确：用 reactive + 属性赋值 const user = reactive({ name: 'Alice', age: 25 }) const fullName = computed(() => `${user.name} (${user.age})`) // 修改：user.name = 'Bob'; user.age = 30 → fullName 自动更新

4.3Failed to resolve component: xxx—— 动态组件加载失败的路径与大小写排查

Vue3 的defineAsyncComponent对文件路径和大小写极其敏感，尤其在 Windows 开发、Linux 部署混合环境中。

典型错误命令：

// ❌ 错误：路径含大写字母，但文件实际为小写 component: () => import('@/views/UserList.vue') // 实际文件名为 userlist.vue // ❌ 错误：路径使用反斜杠（Windows 风格），Vite 不识别 component: () => import('@/views\\UserList.vue')

验证方法：
在浏览器开发者工具 Sources 面板中，展开webpack://或vite://，搜索UserList.vue，确认实际加载的文件名是否与import()路径完全一致（包括大小写、扩展名、斜杠方向）。

标准化写法：
始终使用正斜杠/，路径全小写，.vue后缀不可省略：

// ✅ 正确 component: () => import('@/views/user-list.vue')

同时，在tsconfig.json中启用严格路径检查：

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }

5. 进阶技巧：用vite-plugin-inspect可视化分析构建产物与依赖图谱

Vite 构建过程高度抽象，新手常困惑：“我装了axios，为什么打包后体积没变？”、“lodash-es的 tree-shaking 有没有生效？”。vite-plugin-inspect提供实时可视化界面，直接看到每个模块的依赖关系、代码分割结果和压缩前后体积。

5.1 安装并启用插件

npm install -D vite-plugin-inspect

// vite.config.ts import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import Inspect from 'vite-plugin-inspect' export default defineConfig({ plugins: [ vue(), Inspect(), // 插入到其他插件之后 ], })

启动开发服务器后，访问http://localhost:5173/__inspect/即可打开分析面板。

5.2 用依赖图谱定位冗余包与未使用导出

在Dependencies标签页中，输入lodash-es，查看其所有被引用的路径。若发现某处引用了lodash-es的cloneDeep，但实际代码中只用了isEmpty，说明存在未使用的导入。

优化示例：
将宽泛导入改为精确导入：

// ❌ 宽泛导入，tree-shaking 效果差 import _ from 'lodash-es' _.isEmpty(obj) // ✅ 精确导入，Vite 可彻底剔除未用代码 import { isEmpty } from 'lodash-es' isEmpty(obj)

在Chunks标签页中，点击vendorchunk，查看其中包含哪些第三方模块。若moment出现在 vendor 中，但项目实际只用dayjs，说明有隐式依赖（如某 UI 库内部引用了moment）。此时应检查package-lock.json中moment的来源路径，并考虑升级该 UI 库或使用别名替换：

// vite.config.ts export default defineConfig({ resolve: { alias: { moment: 'dayjs', } } })

5.3 用构建分析报告识别首屏加载瓶颈

执行构建并生成分析报告：

npm run build -- --report

生成dist/report.html，用浏览器打开。重点关注Assets表格中的JS文件：

若index-*.js过大（>150 KiB），说明业务代码未有效分割。此时可在路由中启用异步组件懒加载：

// src/router/index.ts { path: '/dashboard', name: 'Dashboard', component: () => import('@/views/Dashboard.vue'), // ✅ 已懒加载 }, { path: '/reports', name: 'Reports', component: () => import('@/views/Reports.vue').then(m => m.Reports), // ✅ 指定命名导出，进一步减小 chunk },

提示：import(...).then(m => m.xxx)语法可让 Vite 将该模块单独打包为一个 chunk，避免因命名导出未被引用而导致整个模块被保留。配合vite-plugin-inspect的Chunks视图，可直观验证分割效果。

本文还有配套的精品资源，点击获取