Vue3集成NProgress进度条的完整实践：安装、封装、Axios与路由守卫

脚本专家

在Vue3项目中，一个运行中的进度条能显著提升用户体验，尤其适合长耗时请求或页面切换场景。NProgress作为轻量级进度条库，搭配TypeScript和Vite环境，可优雅地融入现有项目。下面分享一套经过验证的集成方案，涵盖基础安装、可配置Hook封装、Axios拦截器和Vue Router守卫集成，以及全局样式自定义。

一、环境准备
首先安装核心依赖和类型定义：

2. pnpm i nprogress lodash-es
3. pnpm i @types/nprogress @types/lodash-es -D

复制代码

nprogress提供进度控制API，lodash-es用于对象深度合并。类型声明仅在开发时使用。

通过环境变量控制进度条开关，在.env文件中加入：

2. VITE_ROUTER_NPROGRESS = true
3. VITE_REQUEST_NPROGRESS = true

复制代码

设置为'false'即可关闭对应场景的进度条，无需修改代码。

二、核心封装：useProgress Hook
创建一个可复用的组合式函数，统一配置进度条行为。

2. // src/hooks/useProgress.ts
3. import { merge } from 'lodash-es'
4. import NProgress from 'nprogress'
5. import type { NProgressOptions } from 'nprogress'
7. interface ProgressConfig extends NProgressOptions {
8.   show: boolean
9. }
11. const DEFAULT_CONFIG: Partial<ProgressConfig> = {
12.   easing: 'ease',
13.   parent: 'body',
14.   show: true,
15.   showSpinner: false,
16.   trickle: true,
17.   minimum: 0.08,
18.   speed: 200,
19. }
21. export function useProgress(config: Partial<ProgressConfig> = {}) {
22.   const mergeConfig = merge({}, DEFAULT_CONFIG, config)
23.   NProgress.configure(mergeConfig)
25.   function start() {
26.     if (!mergeConfig.show) return
27.     NProgress.start()
28.   }
30.   function done() {
31.     if (!mergeConfig.show || !NProgress.isStarted()) return
32.     NProgress.done()
33.   }
35.   return { start, done }
36. }

复制代码

该Hook接受自定义配置，与默认配置深度合并后调用NProgress.configure。start和done方法根据show属性决定是否实际执行，避免因环境变量关闭带来的无谓调用。

三、实际应用场景
1. Axios请求拦截器集成
创建通用请求模块，在请求发送前启动进度条，请求完成后结束。

2. // src/utils/request.ts
3. import axios from 'axios'
4. import { useProgress } from '@/hooks/useProgress'
6. const NProgress = useProgress({ show: import.meta.env.VITE_REQUEST_NPROGRESS !== 'false' })
8. const instance = axios.create({
9.   baseURL: import.meta.env.VITE_API_BASE_URL,
10.   timeout: 15000,
11. })
13. instance.interceptors.request.use(
14.   (config) => {
15.     NProgress.start()
16.     return config
17.   },
18.   (error) => {
19.     NProgress.done()
20.     return Promise.reject(error)
21.   }
22. )
24. instance.interceptors.response.use(
25.   (response) => {
26.     NProgress.done()
27.     return response
28.   },
29.   (error) => {
30.     NProgress.done()
31.     return Promise.reject(error)
32.   }
33. )
35. export const request = instance

复制代码

注意：在请求或响应错误时也要调用done，防止进度条卡住。

2. Vue Router路由守卫集成
在路由切换时自动显示进度条，通过环境变量控制。

2. // src/router/index.ts
3. import { createRouter, createWebHistory } from 'vue-router'
4. import { useProgress } from '@/hooks/useProgress'
6. const router = createRouter({
7.   history: createWebHistory(),
8.   routes: [],
9. })
11. const NProgress = useProgress({ show: import.meta.env.VITE_ROUTER_NPROGRESS !== 'false' })
13. router.beforeEach((to, from, next) => {
14.   NProgress.start()
15.   next()
16. })
18. router.afterEach(() => {
19.   NProgress.done()
20. })
22. export default router

复制代码

若使用了异步路由，确保在路由解析完成后执行done，避免过早结束。

3. 组合式调用示例
在Vue组件的任何异步操作中也可手动调用：

2. <script setup lang="ts">
3. import { useProgress } from '@/hooks/useProgress'
5. const NProgress = useProgress({ show: import.meta.env.VITE_REQUEST_NPROGRESS !== 'false' })
7. async function loadData() {
8.   NProgress.start()
9.   try {
10.     await fetch('/api/data')
11.   } finally {
12.     NProgress.done()
13.   }
14. }
15. </script>

复制代码

务必使用try...finally确保进度条能正确结束。

四、全局样式自定义
NProgress默认提供朴素样式，通常需与项目主题匹配。推荐在全局样式入口文件中覆盖。

创建src/styles/nprogress.scss，定义渐变色进度条：

2. // src/styles/nprogress.scss
3. #nprogress .bar {
4.   background: var(--el-color-primary);
5.   height: 3px;
6.   background: linear-gradient(90deg, var(--el-color-primary-light-3) 0%, var(--el-color-primary) 100%);
7. }
9. #nprogress .peg {
10.   box-shadow: 0 0 10px var(--el-color-primary);
11. }
13. #nprogress .spinner-icon {
14.   border-top-color: var(--el-color-primary);
15.   border-left-color: var(--el-color-primary);
16. }

复制代码

然后新建src/styles/index.scss，统一导入：

2. @use 'nprogress.scss';
3. @use 'variables.scss';
4. @use 'transition.scss';
5. @use 'element-plus/el-table.scss';
6. @use 'element-plus/el-dialog.scss';
7. @use 'element-plus/el-dropdown.scss';
9. body {
10.   font-family: var(--el-font-family);
11.   background-color: var(--el-bg-color-page);
12. }

复制代码

最后在main.ts引入：

2. import { createApp } from 'vue'
3. import App from './App.vue'
4. import './styles/index.scss'
6. const app = createApp(App)
7. app.mount('#app')

复制代码

注意：如果有其他样式文件，顺序需处理好。若不需要自定义，也可以直接引入nprogress自带的CSS：

2. @use 'nprogress/nprogress.css';

复制代码

五、NProgress配置项详解
配置项支持以下参数（配置通过NProgress.configure传入）：

2. {
3.   easing: 'ease',       // CSS3缓动函数
4.   speed: 200,           // 动画速度(ms)
5.   trickle: true,        // 是否自动递增
6.   trickleSpeed: 200,    // 自动递增速度
7.   minimum: 0.08,        // 起始百分比(0-1)
8.   showSpinner: false,   // 是否显示环形加载动画
9.   parent: 'body',       // 父容器CSS选择器
10.   positionUsing: '',    // 定位方式（可选'absolute','fixed'等）
11. }

复制代码

缓动函数推荐使用标准值或自定义贝塞尔曲线，例如：

2. const EASING_FUNCTIONS = {
3.   linear: 'linear',
4.   ease: 'ease',
5.   smooth: 'cubic-bezier(0.4, 0, 0.2, 1)',
6.   gentle: 'cubic-bezier(0.25, 0.1, 0.25, 1)',
7.   swift: 'cubic-bezier(0.4, 0, 0.6, 1)',
8. }

复制代码

可根据项目视觉风格灵活调整。

以上方案已在多个Vue3+TypeScript项目中使用，通过环境变量和配置Hook，能轻松控制进度条的显示与行为，并与Axios、Vue Router深度整合。希望这套封装能帮你快速落地NProgress，提升应用的用户反馈体验。

热心网友1

感谢楼主的详细分享！正好最近在重构一个Vue3项目，进度条这块一直想整合但没找到清晰的方案。你这种通过环境变量控制开关的思路很实用，特别是用lodash-es做深度合并来统一配置，既灵活又干净。请教一下，在路由守卫里如果用了异步路由（比如动态加载组件），有没有遇到过进度条提前结束的情况？我看你提到了“确保在路由解析完成后执行done”，具体是怎么判断解析完成的？另外，组件里手动调用时，如果并发多个请求，start/done的配对会不会有冲突？希望再展开说说，谢谢！