hzqaq的开发日记 - vue3
type: channel
link: https://gyqaq.fun/index.php/category/vue3/
description: vue3
items: Vue前端项目部署教程
items: Vue项目部署到 Nginx 子路径后侧边栏消失——循环依赖排查全记录
items: Vue项目部署到 Nginx 子路径白屏问题排查与解决
items: Vue3教程

Vue前端项目部署教程
type: item
date: 2026-06-25T16:27:10+08:00
description: 基础准备工作打包项目将本地调试好的项目进行打包 使用npm run build获得打包后的静态文件dist文件夹nginxNginx 有一个非常重要的配置文件 nginx.conf，这个是 Nginx 的核心配置文件。1 nginx.conf的路径可以使用如下命令查看一下 Nginx 的相关路径：# 查看Nginx项目文件目录 whereis nginx如果使用源码的安装方式，查看 Nginx 相关文件路径：doubi@doubibiji-server:~$ whereis nginx nginx: /usr/local/nginx doubi@doubibiji-server:~$ ls /usr/local/nginx conf html nginx.pid sbinNginx 相关文件都在 Nginx 安装路径下，核心配置文件 nginx.conf 在 conf 目录下。 可以进入到 html 路径下，里面有 Nginx 首页 index.html 。如果是 apt 或 yum 的安装方式，配置文件在 /etc/nginx 目录下，其中就包含了核心配置文件 nginx.conf 。2 查看nginx.conf查看 nginx.conf 配置文件，可以看到内容如下，其他的配置先忽略：（不同版本，不同安装方式，配置文件的内容可能有差别。）worker_processes 1; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; server { listen 80; # 监听80端口 server_name localhost; location / { # 拦截所有请求 root html; # 指定用于存放网站文件的目录 index index.html index.htm; # 指定首页文件 } } }可以看到 server 监听的是 80 端口，location / 表示拦截 80 端口所有的请求，root html 指定了系统中用于存放网站文件的根目录。在这里，html 是相对路径，相对于 /usr/local/nginx 目录的路径，也可以配置为绝对路径。当使用 http://192.168.0.103 （我的Nginx服务器地址）访问的时候，因为后面没有端口号，所以默认会访问到 Nginx 监听的 80 端口，location / 拦截到了所有的请求，然后去 html 下找对应的页面，因为请求地址后面也没有其他路径，相当于访问 http://192.168.0.103/ ，后面的 / 是根路径，访问的就是首页，显示 index.html 的内容。3.2 发布静态资源使用 Nginx 可以发布静态资源，只需要将静态资源放到 nginx.conf 配置文件中指定的站点目录下就可以了。我将前面打包的静态资源放到html目录下：打包好的静态资源html目录- html -assets -models -pio -favicon.png -favicon.svg -icaons.svg -index.html然后我就可以在浏览器中进行访问了。3.3 nginx.conf配置解析上面查看 nginx.conf 配置的时候，列出来的是 nginx 需要正常工作的最小配置。下面对 nginx.conf 中的内容进行一些简单的说明（不同版本或安装方式，默认配置可能会有一些出入）：user nginx; # 指定Nginx worker进程运行的用户，有的版本是注释掉的#user nobody，不写也表示nobody，nobody是一个特殊的系统用户，通常被用于运行服务进程，它的权限被设置为最低，仅用于限制服务进程的权限，以提高系统安全性。还可以修改为root用户执行，这样权限比较高，不推荐。 worker_processes auto; # 见下面的Nginx进程讲解 error_log /var/log/nginx/error.log warn; # 错误日志文件的路径和日志级别 # Nginx中日志级别分为：debug、info、notice、warn、error、crit等，可以根据日志级别，将不同等级的日志输出到不同的文件中 # 上面表示将大于等于warn等级的日志输出到/var/log/nginx/error.log文件中 # 注释掉就会使用默认配置 pid /var/run/nginx.pid; # 指定存储进程ID文件的路径，在 Nginx 启动时，它会将主进程的 PID 写入到这个文件中 # 我们可以使用进程ID对Nginx进行一些操作，例如停止或重启 event…

Vue项目部署到 Nginx 子路径后侧边栏消失——循环依赖排查全记录
type: item
date: 2026-05-26T12:02:00+08:00
description: 问题背景Vue 3 + Vite 项目部署到 Nginx 子路径 /qk/ 下。本地 npm run dev 一切正常，侧边栏正常显示；但 npm run build 打包上传到宝塔服务器后，侧边栏凭空消失，页面只剩主内容区。环境Vue 3 + Vue Router 5 + Vite 8Element Plus 2.14Nginx（宝塔面板）部署路径：/qk/（非根目录）现象环境表现npm run dev侧边栏正常显示，导航正常生产部署侧边栏完全消失，主内容区直接裸渲染浏览器无任何 JS 报错，所有 JS/CSS 资源均返回 200。排查过程第一阶段：确认不是常见问题先排除最基础的几个原因：1. 资源加载 — Network 面板确认所有 JS/CSS 返回 200，无 404。2. Nginx 配置 — 确认 try_files 配置正确：location ^~ /qk { try_files $uri $uri/ /qk/index.html; }3. Vite base 和 Router base — 确认两处配置一致：// vite.config.ts export default defineConfig({ base: '/qk/', }) // src/router/index.ts const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes, })这些都没问题。import.meta.env.BASE_URL 在构建时会被替换为 /qk/，和 vite.config.ts 中的 base 保持一致。第二阶段：检查 DOM在浏览器 Console 中检查侧边栏相关的 DOM 元素：document.querySelector('.el-aside') // null document.querySelector('.el-menu') // null document.querySelector('.layout-container') // null侧边栏相关的 DOM 元素完全不存在，不是 CSS 隐藏的问题，而是根本没有渲染。同时检查 #app 的内容：document.querySelector('#app').innerHTML.substring(0, 200) // 输出： 欢迎您...Home 组件的内容直接渲染在 #app 里，没有经过 MainLayout 的包裹。这说明 MainLayout 组件没有被渲染。第三阶段：确认构建产物正确对比本地构建产物和服务器上的文件：# 本地文件 SHA1 shasum < dist/assets/index-CkDFcajS.js # aca210159051a4f72f68479f947d1df1d1641c96 # 服务器文件 SHA1 curl -s https://gyqaq.fun/qk/assets/index-CkDFcajS.js | shasum # aca210159051a4f72f68479f947d1df1d1641c96SHA1 完全一致，排除部署问题。在构建产物中搜索 MainLayout 的模板内容：grep -o 'layout-container' dist/assets/index-CkDFcajS.js # 存在 grep -o '轻客管家' dist/assets/index-CkDFcajS.js # 存在MainLayout 的代码确实在构建产物中，没有被 tree-shaking 掉。第四阶段：检查路由匹配在浏览器 Console 中检查 Vue Router 的运行时状态：const app = document.querySelector('#app').__vue_app__ const router = app.config.globalProperties.$router const route = router.currentRoute.value console.log('路径:', route.path) // 输出：/home console.log('匹配的路由:', route.matched.map(r => ({ path: r.path, name: r.name }))) // 输出： // [{ path: '/', name: 'main' }, ← MainLayout // { path: '/home', name: 'home' }] ← Home路由匹配完全正确，MainLayout 和 Home 都被匹配到了。第五阶段：定位根因继续检查 Main…

Vue项目部署到 Nginx 子路径白屏问题排查与解决
type: item
date: 2026-05-26T11:56:00+08:00
description: 问题描述Vue 3 + Vite 项目部署到 Nginx 服务器的子路径 /qk/ 下，访问页面时出现白屏，浏览器控制台无明显 JS 报错。环境Vue 3 + Vue Router 5 + ViteNginx（宝塔面板）部署路径：/qk/（非根目录）排查过程1. 检查资源加载（排除资源 404）打开浏览器 F12 → Network 面板，确认所有 JS/CSS 文件均返回 200：资源加载正常，排除资源路径问题。2. 检查控制台报错Console 中仅有 SES Removing unpermitted intrinsics，这是 MetaMask 等浏览器扩展的日志，与项目无关。3. 定位根因：Router 路径不匹配资源加载正常、无 JS 报错，但页面空白 —— 说明 Vue Router 没有匹配到任何路由，导致无组件渲染。原因分析：应用部署在 /qk/ 子路径下用户访问 https://gyqaq.fun/qk/Vue Router 使用 createWebHistory() 未设置 base 路径Router 将完整路径 /qk/ 去匹配路由表，但路由表中只有 /、/home、/login 等没有路由匹配 → 无组件渲染 → 白屏解决方案需要同时修改两处配置：1. vite.config.ts — 设置 baseexport default defineConfig({ base: '/qk/', // 构建产物的资源路径前缀 // ... })这一步让 Vite 构建时，index.html 中引用的 JS/CSS 路径变为 /qk/assets/xxx，而不是 /assets/xxx。2. src/router/index.ts — 设置 Router baseconst router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), // 路由基准路径 routes, })这一步让 Vue Router 知道应用运行在 /qk/ 下，路由匹配时会正确处理路径前缀。3. 重新构建部署npm run build将 dist 目录内容上传到服务器 /www/wwwroot/gyqaq.fun/qk/ 下。Nginx 配置参考location ^~ /qk { try_files $uri $uri/ /qk/index.html; }try_files 确保所有未匹配的路径都回退到 index.html，交给前端路由处理（SPA 的核心配置）。总结配置项作用缺失后果vite.base资源文件路径前缀JS/CSS 404（如部署在根目录则无影响）createWebHistory(base)路由基准路径路由无法匹配，白屏nginx try_filesSPA 回退到 index.html刷新页面 404核心原则：部署到子路径时，vite.config.ts 的 base 和 createWebHistory() 的参数必须与 Nginx 的 location 路径保持一致。

Vue3教程
type: item
date: 2026-05-26T11:43:57+08:00
description: 1. Vue3简介2020年9月18日，Vue.js发布版3.0版本，代号：One Piece（n经历了：4800+次提交、40+个RFC、600+次PR、300+贡献者官方发版地址：Release v3.0.0 One Piece · vuejs/core截止2023年10月，最新的公开版本为：3.3.41.1. 【性能的提升】打包大小减少41%。初次渲染快55%, 更新渲染快133%。内存减少54%。1.2.【 源码的升级】使用Proxy代替defineProperty实现响应式。重写虚拟DOM的实现和Tree-Shaking。1.3. 【拥抱TypeScript】Vue3可以更好的支持TypeScript。1.4. 【新的特性】Composition API（组合API）：setupref与reactivecomputed与watch......新的内置组件：FragmentTeleportSuspense......其他改变：新的生命周期钩子data 选项应始终被声明为一个函数移除keyCode支持作为 v-on 的修饰符......2. 创建Vue3工程2.1. 【基于 vue-cli 创建】点击查看官方文档备注：目前vue-cli已处于维护模式，官方推荐基于 Vite 创建项目。## 查看@vue/cli版本，确保@vue/cli版本在4.5.0以上 vue --version ## 安装或者升级你的@vue/cli npm install -g @vue/cli ## 执行创建命令 vue create vue_test ## 随后选择3.x ## Choose a version of Vue.js that you want to start the project with (Use arrow keys) ## > 3.x ## 2.x ## 启动 cd vue_test npm run serve2.2. 【基于 vite 创建】(推荐)vite 是新一代前端构建工具，官网地址：https://vitejs.cn，vite的优势如下：轻量快速的热重载（HMR），能实现极速的服务启动。对 TypeScript、JSX、CSS 等支持开箱即用。真正的按需编译，不再等待整个应用编译完成。webpack构建 与 vite构建对比图如下： 具体操作如下（点击查看官方文档）## 1.创建命令 npm create vue@latest ## 2.具体配置 ## 配置项目名称 √ Project name: vue3_test ## 是否添加TypeScript支持 √ Add TypeScript? Yes ## 是否添加JSX支持 √ Add JSX Support? No ## 是否添加路由环境 √ Add Vue Router for Single Page Application development? No ## 是否添加pinia环境 √ Add Pinia for state management? No ## 是否添加单元测试 √ Add Vitest for Unit Testing? No ## 是否添加端到端测试方案 √ Add an End-to-End Testing Solution? » No ## 是否添加ESLint语法检查 √ Add ESLint for code quality? Yes ## 是否添加Prettiert代码格式化 √ Add Prettier for code formatting? No//vite创建自动映射 router路径 { "extends": "@vue/tsconfig/tsconfig.dom.json", "include": ["env.d.ts", "src/**/*", "src/**/*.vue"], "exclude": ["src/**/__tests__/*"], "compilerOptions": { // Extra safety for array and object lookups, but may have false positives. "noUncheckedIndexedAccess": true, // Path mapping for cleaner imports. "paths": { "@/*": ["./src/*"] }, // `vue-tsc --build` produces a .tsbuildinfo file for incremental type-checking. // Specified here to keep it out of the root director…