JS 各项目库版本兼容清单（稳定无冲突，2026 推荐）
区分三大场景：原生静态页面、Vue3 (Vite)、React (Vite)，附带 Node 后端配套版本，所有版本为长期稳定版，不会出现 API 废弃、依赖冲突。
一、通用基础库（全项目通用兼容版本）
| 库名称 | 稳定版本 | 兼容说明 |
|---|---|---|
| axios | v1.7.x | 支持浏览器 / Node，兼容 Vue2/3、React17/18，无破坏性更新 |
| dayjs | v1.11.x | 完全替代 moment，API 一致，无兼容性问题 |
| lodash | v4.17.21 | 最终稳定大版本，不再更新，全框架兼容 |
| zod | v3.23.x | 表单 / 数据校验，TS 完美支持，Vue/React 通用 |
| xlsx(SheetJS) | v0.18.x | Excel 导入导出，无依赖冲突 |
| gsap | v3.12.x | 动画库，轻量、无框架耦合 |
| echarts | v5.4.x | 图表，兼容所有前端环境，vue-echarts/echarts-for-react 适配该版本 |
| crypto-js | v4.2.x | 前端加密 |
| clipboard | v2.0.x | 复制文本 |
二、Vue3 项目（Vite，Vue3.4 主线，稳定配套）
核心框架生态（强制配套，避免版本报错）
| 依赖包 | 锁定版本 | 配套规则 |
|---|---|---|
| vue | 3.4.x | 主框架，不要升级 3.5 测试版 |
| vue-router | 4.2.x | 仅适配 Vue3，和 vue3.4 完美兼容 |
| pinia | 2.1.x | Vue 官方状态库，替代 vuex，兼容 vue3.4 |
| vue-echarts | 6.6.x | 适配 echarts5.4.x，配套使用 |
UI 组件库兼容版本
- Element Plus（PC 后台）：
element-plus@2.4.x - Vant4（移动端 H5）：
vant@4.8.x
Vue3 完整安装命令（复制直接用，无冲突）
# 核心生态 npm install vue@3.4.33 vue-router@4.2.5 pinia@2.1.7 # 通用工具 npm install axios@1.7.4 dayjs@1.11.10 lodash@4.17.21 zod@3.23.8 # 图表+文件+动画 npm install echarts@5.4.3 vue-echarts@6.6.1 xlsx@0.18.5 gsap@3.12.5 # PC UI npm install element-plus@2.4.9三、React 项目（Vite，React18 稳定主线）
核心框架生态配套版本
| 依赖包 | 锁定版本 | 兼容说明 |
|---|---|---|
| react / react-dom | 18.2.x | 主流稳定版，不推荐 19 测试版 |
| react-router-dom | 6.20.x | 适配 react18，路由 API 统一 |
| zustand | 4.4.x | 轻量状态管理，无冗余依赖 |
| echarts-for-react | 3.0.2 | 适配 echarts5.4.x |
UI 组件库兼容版本
- Ant Design（企业后台）：
antd@5.12.x - MUI 谷歌风格：
@mui/material@5.15.x
React 完整安装命令（直接复制）
# 核心框架+路由+状态 npm install react@18.2.0 react-dom@18.2.0 react-router-dom@6.20.0 zustand@4.4.7 # 通用工具 npm install axios@1.7.4 dayjs@1.11.10 lodash@4.17.21 zod@3.23.8 # 图表、Excel、动画 npm install echarts@5.4.3 echarts-for-react@3.0.2 xlsx@0.18.5 gsap@3.12.5 # Ant Design后台UI npm install antd@5.12.2四、Node.js 后端（Express / NestJS 版本兼容）
1. Express 轻量后端稳定组合
# 框架基础 npm install express@4.18.2 cors@2.8.5 body-parser@1.20.2 # 文件上传、数据库、鉴权 npm install multer@1.4.5-lts.1 mysql2@3.6.5 jsonwebtoken@9.0.2 joi@17.11.02. NestJS 企业级 TS 后端配套
# ORM数据库 npm install @nestjs/typeorm@10.0.1 typeorm@0.3.17 mysql2@3.6.5 # JWT登录鉴权 npm install @nestjs/jwt@10.2.0 @nestjs/passport@10.0.2 passport-jwt@4.0.1 # 参数校验 npm install class-validator@0.14.0 class-transformer@0.5.1五、版本冲突避坑规则（重点）
- echarts 配套规则echarts5.x 必须搭配 vue-echarts6.x/echarts-for-react3.x； 不要混用 echarts4.x，API 差异极大。
- 框架大版本隔离
- Vue2 不能安装 vue-router4、pinia；Vue3 不兼容 vue-router3、vuex 旧版
- React17 项目不要直接升级 antd5，会出现组件渲染报错
- Lodash TS 类型包TS 项目额外安装类型提示，版本固定：
npm install -D @types/lodash@4.14.200 - 不要使用 ^、~ 模糊版本生产环境建议锁定版本，
package.json写死版本号，避免自动升级大版本引发线上 bug。 - 打包工具兼容Vite4.x 适配 Vue3.4、React18；Webpack5 可兼容以上所有库，无冲突。
六、CDN 引入版本（原生静态页面，稳定 CDN 地址）
html
<!-- 基础工具 --> <script src="https://cdn.jsdelivr.net/npm/axios@1.7.4/dist/axios.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/dayjs@1.11.10/dayjs.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script> <!-- 图表 --> <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>