Element Plus加载动画不显示的排查与解决方案-平芜编程栈

1. 问题现象与背景分析

最近在项目中使用Element Plus的ElLoading.service时遇到了一个典型问题：明明设置了spinner属性，但加载动画始终不显示。这个问题看似简单，却困扰了不少开发者。Element Plus作为Vue 3的主流UI库，其Loading组件在日常开发中使用频率极高，特别是在管理后台类项目中。

通过社区反馈和issue排查，我发现这个问题通常发生在以下场景：

使用ElLoading.service全屏加载时
自定义了spinner属性但未生效
升级Element Plus版本后出现异常

2. 核心原因排查

2.1 基础配置检查

首先需要确认的是基础配置是否正确。ElLoading.service的标准用法应该是：

const loadingInstance = ElLoading.service({ lock: true, text: '加载中...', spinner: 'el-icon-loading', // 关键配置项 background: 'rgba(0, 0, 0, 0.7)' })

常见配置错误包括：

拼写错误：将spinner写成spiner等
图标名称错误：未使用Element Plus官方支持的图标名称
未正确导入图标组件

2.2 图标库依赖分析

Element Plus从2.2.0版本开始，将图标组件拆分为独立包。这意味着：

如果你使用的是完整引入方式：

import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' app.use(ElementPlus)

仍需额外安装并导入图标库：

npm install @element-plus/icons-vue

如果是按需引入，需要确保：

import { Loading } from '@element-plus/icons-vue' app.component('el-icon-loading', Loading)

2.3 版本兼容性问题

通过issue分析，发现以下版本存在已知问题：

2.0.0-2.1.0：部分图标注册异常
2.2.0+：需要独立安装图标包

建议检查package.json中的版本：

"dependencies": { "element-plus": "^2.3.3", "@element-plus/icons-vue": "^2.1.0" }

3. 完整解决方案

3.1 基础修复方案

对于大多数情况，以下三步即可解决：

安装图标库：

npm install @element-plus/icons-vue

全局注册图标（main.js/ts）：

import * as ElementPlusIconsVue from '@element-plus/icons-vue' const app = createApp(App) for (const [key, component] of Object.entries(ElementPlusIconsVue)) { app.component(key, component) }

确保使用正确的图标名称：

spinner: 'el-icon-loading' // 注意前缀el-icon-

3.2 高级自定义方案

如果需要使用自定义加载动画：

创建自定义组件CustomSpinner.vue：

<template> <div class="custom-spinner"> <!-- 你的动画实现 --> </div> </template> <script> export default { name: 'CustomSpinner' } </script>

注册组件后使用：

import CustomSpinner from './components/CustomSpinner.vue' app.component('CustomSpinner', CustomSpinner) // 使用 ElLoading.service({ spinner: 'CustomSpinner' })

3.3 动态加载方案

对于需要动态切换spinner的场景：

const loadings = { default: 'el-icon-loading', custom: 'CustomSpinner' } const loadingInstance = ElLoading.service({ spinner: loadings[type] })

4. 深度问题排查指南

4.1 检查DOM结构

在浏览器开发者工具中检查生成的DOM：

应该存在.el-icon-loading元素
检查是否有CSS覆盖导致隐藏
确认图标字体/图片是否加载成功

4.2 样式覆盖问题

常见样式冲突：

/* 错误示例：会隐藏加载图标 */ .el-loading-spinner { display: none !important; } /* 正确覆盖方式 */ .el-loading-spinner { color: #409eff !important; }

4.3 版本降级方案

如果确实无法升级，可回退到1.x版本：

npm install element-plus@1.3.0-beta.5

但会失去Vue 3的新特性支持。

5. 最佳实践与性能优化

5.1 全局配置建议

在项目入口统一配置：

import { ElLoading } from 'element-plus' ElLoading.config({ spinner: 'el-icon-loading', background: 'rgba(0, 0, 0, 0.5)' })

5.2 服务化封装

建议封装loading服务：

// utils/loading.js let loadingInstance export const showLoading = (options) => { loadingInstance = ElLoading.service({ spinner: 'el-icon-loading', ...options }) } export const hideLoading = () => { loadingInstance?.close() }

5.3 性能注意事项

避免频繁创建/销毁实例
单例模式管理全局loading
大数据量场景下使用局部loading

6. 常见问题速查表

问题现象	可能原因	解决方案
不显示spinner	未安装图标库	npm install @element-plus/icons-vue
控制台报错图标未注册	未全局注册图标	按3.1节注册图标
显示方块而非图标	字体加载失败	检查网络和字体文件
自定义组件不显示	组件未注册	确保全局注册自定义组件
升级后失效	版本不兼容	检查版本对应关系

7. 版本升级指南

从Element UI迁移到Element Plus时需特别注意：

图标前缀从el-icon改为el-icon-
图标组件需要单独安装
服务调用方式从this.$loading改为直接导入

推荐升级路径：

备份当前项目
逐步替换组件
使用@element-plus/icons-vue替换旧版图标
测试所有loading场景

8. 扩展应用场景

8.1 表格加载优化

结合el-table使用：

const table = ref(null) const loading = ref(false) const fetchData = async () => { loading.value = true try { const res = await api.getData() table.value.reloadData(res) } finally { loading.value = false } }

8.2 路由切换loading

在路由守卫中使用：

router.beforeEach(() => { showFullScreenLoading() }) router.afterEach(() => { hideFullScreenLoading() })

8.3 按钮级微调

对于特定按钮的loading状态：

<el-button :loading="btnLoading" loading-icon="el-icon-loading" > 提交 </el-button>

9. 源码解析

理解ElLoading.service的实现原理有助于更好使用：

创建Loading组件实例
通过Vue的render函数挂载到DOM
维护全局loading状态
通过teleport实现全屏效果

关键源码片段：

// element-plus/packages/components/loading/src/service.ts const loadingInstance = createVNode( LoadingComponent, { ...options, visible: true, closed: () => { // 清理逻辑 } } )

10. 替代方案对比

当ElLoading不满足需求时，可以考虑：

使用CSS动画实现：

@keyframes spin { to { transform: rotate(360deg); } } .custom-loader { animation: spin 1s linear infinite; }

第三方库如：

vue-loading-overlay
nprogress（顶部进度条）
spin.js（纯JS实现）

框架自带解决方案：

Vue 3的Suspense组件
Nuxt.js的loading配置

11. 测试验证方案

为确保loading功能稳定：

单元测试示例：

import { mount } from '@vue/test-utils' import { ElLoading } from 'element-plus' test('should display loading spinner', async () => { const loading = ElLoading.service() expect(document.querySelector('.el-icon-loading')).not.toBeNull() loading.close() })

E2E测试要点：

验证DOM存在
检查动画是否运行
确认关闭后DOM移除

12. 设计规范建议

保持UI一致性：

加载时间建议：

<0.5s：不需要loading
0.5-2s：使用微调
2s：全屏loading

视觉设计原则：

与品牌色一致
不遮挡关键操作
提供取消选项（长时间加载时）

13. 移动端适配技巧

针对移动端的特殊处理：

禁用背景滚动：

ElLoading.service({ lock: true, // 移动端专用配置 body: true, customClass: 'mobile-loading' })

响应式样式：

@media (max-width: 768px) { .el-loading-spinner { width: 80vw; } }

14. 国际化支持

多语言场景下的处理：

动态加载文本：

const i18nMessages = { en: { loading: 'Loading...' }, zh: { loading: '加载中...' } } ElLoading.service({ text: i18nMessages[currentLang].loading })

图标方向适配：

[dir='rtl'] .el-icon-loading { animation-direction: reverse; }

15. 无障碍访问

确保符合WCAG标准：

ARIA属性支持：

ElLoading.service({ spinner: 'el-icon-loading', 'aria-label': '数据加载中' })

键盘可操作性：

允许ESC键取消loading
保持焦点管理

16. 性能监控集成

结合APM工具：

const startTime = Date.now() const loading = ElLoading.service() performance.mark('loading_start') loading.close() performance.mark('loading_end') performance.measure('loading_duration', 'loading_start', 'loading_end')

17. 服务端渲染(SSR)处理

Nuxt.js中的特殊处理：

组件方式：

<client-only> <el-button @click="showLoading">加载</el-button> </client-only>

插件配置：

// plugins/element.js export default defineNuxtPlugin(nuxtApp => { nuxtApp.$loading = () => { if (process.client) { return ElLoading.service() } } })

18. 状态管理集成

与Pinia/Vuex结合：

// stores/loading.js export const useLoadingStore = defineStore('loading', { actions: { show() { this.instance = ElLoading.service() }, hide() { this.instance?.close() } } })

19. 动画效果进阶

自定义高级动画：

Lottie动画集成：

import lottie from 'lottie-web' ElLoading.service({ spinner: 'div', // 占位元素 onMounted(el) { lottie.loadAnimation({ container: el.querySelector('.el-loading-spinner'), renderer: 'svg', loop: true, autoplay: true, path: '/loading.json' }) } })

CSS变量控制：

.el-loading-spinner { --loading-speed: 0.8s; animation-duration: var(--loading-speed); }

20. 错误边界处理

健壮性增强方案：

let loadingInstance try { loadingInstance = ElLoading.service() await criticalOperation() } catch (err) { console.error('操作失败', err) // 显示错误状态loading loadingInstance?.setText('加载失败') loadingInstance?.updateSpinnerClass('error-icon') } finally { setTimeout(() => { loadingInstance?.close() }, 1000) }

21. 主题定制方案

配合自定义主题：

修改SCSS变量：

$--loading-spinner-color: $--color-primary; $--loading-background: rgba(0, 0, 0, 0.5);

动态主题切换：

watch(theme, (newTheme) => { ElLoading.config({ spinner: newTheme === 'dark' ? 'dark-spinner' : 'light-spinner' }) })

22. 调试技巧

开发中实用技巧：

强制显示测试：

// 在控制台直接测试 const loading = ElLoading.service() setTimeout(() => loading.close(), 2000)

组件实例检查：

const loading = ElLoading.service() console.log(loading.$el) // 检查DOM console.log(loading.spinner) // 检查spinner状态

23. 组合式API实践

Vue 3新特性应用：

import { ref } from 'vue' import { ElLoading } from 'element-plus' export function useLoading() { const loading = ref(null) const show = (options) => { loading.value = ElLoading.service(options) } const hide = () => { loading.value?.close() loading.value = null } return { show, hide, loading } }

24. TypeScript支持

增强类型安全：

类型定义扩展：

declare module 'element-plus' { interface ILoadingOptions { spinner?: string | Component customClass?: string } }

封装安全调用：

function safeLoading(options: ILoadingOptions) { try { return ElLoading.service(options) } catch (err) { console.error('Loading初始化失败', err) return null } }

25. 微前端场景处理

在qiankun等框架中的特殊处理：

样式隔离方案：

ElLoading.service({ customClass: 'subapp-loading', body: true })

主子应用通信：

// 主应用 window.mainApp = { showLoading: () => ElLoading.service() } // 子应用 window.parent.mainApp?.showLoading()

26. 浏览器兼容性

针对旧版浏览器的polyfill：

动画兼容方案：

ElLoading.service({ spinner: 'el-icon-loading', useCssAnimation: false // 强制使用JS动画 })

字体回退策略：

.el-icon-loading { font-family: "element-icons", sans-serif; }

27. 安全最佳实践

防止XSS攻击：

安全文本处理：

ElLoading.service({ text: sanitizeHtml(userInputText) // 使用DOMPurify等库处理 })

沙箱模式：

const loading = ElLoading.service({ appendTo: document.createElement('div') // 隔离容器 })

28. 内存管理

避免内存泄漏：

实例清理：

onBeforeUnmount(() => { loadingInstance?.close() })

泄漏检测：

const instances = new WeakMap() function trackLoading(instance) { instances.set(instance, new Error('创建堆栈')) }

29. 单元测试进阶

完整测试套件示例：

describe('ElLoading', () => { it('should render with custom spinner', () => { const wrapper = mount(Component, { global: { plugins: [ElementPlus] } }) wrapper.vm.showLoading() expect(document.querySelector('.custom-spinner')).not.toBeNull() }) })

30. 实际项目集成案例

电商后台典型应用：

// 订单列表加载 const loadOrders = async () => { const loading = ElLoading.service({ target: '.order-table', spinner: 'el-icon-refresh', text: '正在获取订单数据...' }) try { await store.dispatch('fetchOrders') } finally { loading.close() } }

31. 性能指标收集

用户感知监控：

const loadingStart = performance.now() const loading = ElLoading.service() new PerformanceObserver((entries) => { const paintTime = entries.getEntriesByName('first-contentful-paint')[0] console.log('Loading阻塞时间:', paintTime.startTime - loadingStart) }).observe({ type: 'paint', buffered: true })

32. 设计系统对接

与Figma设计稿同步：

Token映射：

ElLoading.config({ spinnerColor: 'var(--color-brand-primary)', background: 'var(--overlay-dark)' })

设计规范检查：

function validateLoadingOptions(options) { if (options.background && !isValidColor(options.background)) { console.warn('不符合设计系统颜色规范') } }

33. 移动端原生集成

与Cordova/Capacitor配合：

// 防止原生滚动穿透 ElLoading.service({ lock: true, onOpen() { if (window.cordova) { document.body.style.overflow = 'hidden' } }, onClose() { if (window.cordova) { document.body.style.overflow = '' } } })

34. 微交互优化

增强用户体验：

最小延迟显示：

let loadingTimer const showLoading = () => { loadingTimer = setTimeout(() => { loadingInstance = ElLoading.service() }, 300) // 快速操作不显示 } const hideLoading = () => { clearTimeout(loadingTimer) loadingInstance?.close() }

进度感知：

ElLoading.service({ text: '正在加载 0%', onProgress(percent) { this.setText(`正在加载 ${percent}%`) } })

35. 服务端通信整合

与Axios拦截器配合：

axios.interceptors.request.use(config => { config.metadata = { loading: ElLoading.service() } return config }) axios.interceptors.response.use( response => { response.config.metadata.loading.close() return response }, error => { error.config.metadata.loading.close() return Promise.reject(error) } )

36. 复杂场景解决方案

多loading实例管理：

const loadingStack = [] function pushLoading(options) { const instance = ElLoading.service(options) loadingStack.push(instance) return instance } function popLoading() { const instance = loadingStack.pop() instance?.close() } // 确保后进先出 window.addEventListener('unload', () => { while (loadingStack.length) { popLoading() } })

37. 视觉反馈增强

高级状态反馈：

ElLoading.service({ spinner: 'el-icon-warning', text: '网络不稳定，正在重试...', background: 'rgba(255, 165, 0, 0.5)', customClass: 'warning-loading' })

38. 组件库扩展开发

创建增强版Loading：

import { ElLoading } from 'element-plus' export function createAdvancedLoading(options) { const instance = ElLoading.service(options) return { ...instance, setProgress(percent) { instance.setText(`${percent}%`) }, changeType(type) { instance.updateSpinnerClass(`${type}-spinner`) } } }

39. 国际化动态切换

语言切换实时响应：

const { t } = useI18n() watch(() => i18n.locale, () => { loadingInstance?.setText(t('loading.text')) })

40. 可访问性增强

屏幕阅读器支持：

ElLoading.service({ 'aria-live': 'assertive', 'aria-atomic': 'true', 'aria-label': '系统正在处理中，请稍候' })

41. 主题引擎深度集成

配合CSS-in-JS：

import { useTheme } from 'styled-components' function ThemedLoading() { const theme = useTheme() return ElLoading.service({ background: theme.loadingBg, spinner: theme.loadingIcon }) }

42. 动画性能优化

GPU加速技巧：

.el-loading-spinner { transform: translateZ(0); will-change: transform; }

43. 服务端状态同步

SSR数据预取指示：

// server.js app.use((req, res, next) => { req.loadingState = 'start' next() }) // client.js hydrateApp().then(() => { if (window.__LOADING_STATE__) { ElLoading.service({ text: '正在同步服务器状态...' }) } })

44. 组件测试策略

自动化测试方案：

describe('Loading', () => { it('should accept custom spinner', async () => { const wrapper = mount(Component, { global: { stubs: { 'el-icon-loading': true } } }) await wrapper.find('button').trigger('click') expect(wrapper.findComponent({ name: 'el-icon-loading' }).exists()).toBe(true) }) })

45. 设计模式应用

工厂模式封装：

class LoadingFactory { static create(type, options) { switch (type) { case 'fullscreen': return ElLoading.service(options) case 'local': return ElLoading.service({ target: options.target }) default: throw new Error('未知类型') } } }

46. 状态持久化

页面刷新保持：

// 在页面卸载前保存状态 window.addEventListener('beforeunload', () => { localStorage.setItem('pendingLoading', JSON.stringify(loadingStates)) }) // 页面加载后恢复 onMounted(() => { const states = localStorage.getItem('pendingLoading') if (states) { restoreLoadingStates(JSON.parse(states)) } })

47. 性能分析工具

Chrome DevTools集成：

const loading = ElLoading.service() // 在Performance面板记录 performance.mark('loadingStart') loading.close() performance.mark('loadingEnd') performance.measure('loadingDuration', 'loadingStart', 'loadingEnd')

48. 错误恢复策略

自动重试机制：

let retries = 0 function loadWithRetry() { const loading = ElLoading.service() fetchData() .catch(err => { if (retries < 3) { retries++ loading.setText(`加载失败，正在第${retries}次重试...`) return new Promise(resolve => setTimeout(() => resolve(loadWithRetry()), 1000) ) } throw err }) .finally(() => loading.close()) }

49. 可视化配置工具

通过GUI生成配置：

// 假设有配置生成器 const config = loadingConfigBuilder() .withSpinner('el-icon-loading') .withBackground('#00000080') .build() ElLoading.service(config)

50. 未来演进方向

虽然当前问题有明确解决方案，但可以期待：

更智能的自动隐藏/显示逻辑
内置进度指示功能
更好的SSR支持
与Vue 3 Suspense深度集成

在实际项目中，我通常会创建一个loading工具函数库，封装各种场景下的最佳实践，团队成员只需简单调用即可获得符合产品规范的加载效果，这大大提高了开发效率和用户体验的一致性。