Vue 3 项目配置首屏加载进度条需用 NProgress 在路由跳转开始时调用 start()、结束时调用 done()，通过 minimum、speed 等参数优化体验，配合样式引入与全局配置实现无闪烁的虚拟进度反馈。

Vue 3 项目配置首屏加载进度条，核心是用 NProgress 在路由跳转开始时启动、结束时收尾，并配合合理配置避免闪烁或误触发。它不依赖真实加载时间，而是通过“虚拟进度”提供即时视觉反馈，解决白屏等待感。

安装与基础引入

执行安装命令（推荐 pnpm）：

• pnpm add nprogress
• pnpm add -D @types/nprogress（TypeScript 项目必需）

在项目入口或路由配置前引入样式和库：

• import 'nprogress/nprogress.css' —— 必须，否则无样式
• import NProgress from 'nprogress'

全局配置关键参数

在 src/utils/progress.ts 或 router/index.ts 中调用 NProgress.configure()，重点设以下几项：

立即学习“前端免费学习笔记（深入）”；

vue-composition-api-best-practices

Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。

下载

• minimum: 0.1 ~ 0.3：防止进度条刚启动就瞬间完成，建议设 0.2
• speed: 500 ~ 800：控制从 0 到 100% 的动画时长（毫秒），太快显得突兀
• trickleSpeed: 200：自动递增间隔，保持“流动感”
• showSpinner: false：默认隐藏旋转图标，更符合现代 UI 简洁风格
• parent: 'body'：确保进度条挂载在 body 下，避免被局部容器遮挡

路由守卫中启用

在 router/index.ts 中接入导航守卫：

• router.beforeEach(() => { NProgress.start() }) —— 每次跳转前启动
• router.afterEach(() => { NProgress.done() }) —— 跳转完成后收尾

⚠️ 注意：不要在 beforeEach 的异步逻辑（如权限校验失败）中遗漏 done()，否则进度条会卡住；可统一在 afterEach 收尾更稳妥。

样式微调（可选）

在 App.vue 或全局样式中覆盖默认颜色与高度：

• #nprogress .bar { background: #4687FE; height: 3px; }
• 如需适配深色模式，可用 CSS 变量：background: var(--primary-color, #4687FE);

不复杂但容易忽略