简介：若依Vue3项目压缩包，是一个基于Webpack（而非Vite）构建的后台管理系统完整工程实例，面向Vue.js开发者和若依框架使用者，帮助解决非Vite环境下项目初始化、构建配置、组件整合等实际问题。包内共有2004个文件，其中975个md说明文档适合逐步阅读，966个js源码可直接借鉴，52个json配置用于依赖和项目参数，另有少量html与txt备用，压缩包整体约57.1MB，目录结构清晰。目前已有675人学习下载。除完整项目源码和Webpack配置文件外，还配套有若依框架组件用法笔记、Vue3组合式API应用示例、ECharts图表集成及测试页面，覆盖后台开发中常见的权限、布局、接口调用等场景，适合希望研究Webpack构建细节或维护同类项目的开发者快速上手。
1. 为什么放着官方Vite不用，去找webpack版的若依Vue3
很多刚接触若依Vue3的人都会有同一个疑惑：官方模板默认是Vite，为什么还有人在网上专门找webpack（非Vite）版本？答案其实很现实——不是Vite不好，而是很多公司的存量工程、CI流水线、私有化交付环境都还锁死在webpack体系里。某开发者的团队接手过一个维护中的后台项目，里面几十个页面、十几个自定义loader、老旧的node-sass依赖，全部围着webpack转，让他一个人改成Vite，光是迁移 loader 和调试 devServer 就够他加一个月的班。
这个标题解决的就是这类诉求：在不引入Vite的前提下，把若依Vue3的后台工程跑在webpack上，前端代码、路由、权限、后端接口对接都不变，构建和启动链路换成vue-cli-service serve。适合谁？手里维护着webpack老工程、又要上新若依Vue3的开发者，或者团队规定构建工具必须统一的场景。它不是教你花哨的新技术，而是给你一套从「拿到webpack版代码」到「跑通、改配置、发版」的完整路径。
2. vite版和webpack版差在哪：启动机制、配置入口、依赖管理都要换
2.1 启动链路不同，决定你排查问题的方向也不同
Vite在开发环境走的是原生ESM按需编译，冷启动快是它的最大卖点；但webpack走的是全量打包，把入口文件依赖的模块全部编译成一个bundle再交给浏览器。这个机制差异带来的第一个影响，就是开发时的报错时机和报错形态完全不同。Vite里你改了文件，浏览器会直接并发加载那个模块的ESM版本，语法错误在浏览器控制台里很直接；webpack里则是bundle过程中出错，报错会指向loader、babel配置或者依赖关系，排查方向完全不同。
具体到若依Vue3，官方Vite版启动后访问的是localhost:5173，而webpack版用的是vue-cli-service serve，默认端口是8080。别小看这个差异，很多第一次接触webpack版的人端着Vite的习惯去改端口，满屏找server.port，结果发现根本没这个配置项，端口在vue.config.js里的devServer.port。我把这个差异理解为「构建工具的性格」，Vite给你极简入口，webpack把一切摊开让你自己配，没有谁绝对好，只有谁更适合你的维护场景。
再往下走一步，配置入口的变化更明显。Vite版的若依Vue3根目录下是vite.config.js，里面写着server.proxy、resolve.alias、build.rollupOptions；webpack版则是vue.config.js，配合Vue CLI 5的chainWebpack和configureWebpack两个口子。如果你之前只看过Vite版，刚打开webpack版时大概率找不到北，因为连插件心智都换了，Vite里的@vitejs/plugin-vue对应到vue-loader，define对应到webpack的DefinePlugin，这些概念不重新过一遍，后面改配置会很拧巴。
2.2 环境变量与运行时代码写法要同步改
这是最容易踩、又最隐蔽的一层差异。Vite版里前端代码获取环境变量用的是import.meta.env，比如import.meta.env.VITE_APP_BASE_API；webpack版里则回到process.env.VUE_APP_BASE_API。如果你把一个Vite版的若依Vue3工程直接搬过来不改这些引用，运行时一定会报undefined，接口全部打到当前域名的根路径上，登录请求直接404。
我一般会先用grep把全站的import.meta.env搜出来，替换成process.env.VUE_APP_前缀，同时把根目录下的.env.development和.env.production文件里的变量名前缀也一并改了。这一层虽然机械，但牵一发动全身，漏一处就是一个诡异的线上bug。另外还要注意，Vite版在.env里写的VITE_APP_TITLE这类变量，webpack版只会读取VUE_APP_开头的变量，改文件的时候连注释里的写法也一起改干净，省得后面排查的人迷惑。
依赖管理也一样，Vite版常见的vue-router@4、pinia、element-plus这些运行时依赖在webpack下都用，真正要换的是构建期依赖。常见做法是装@vue/cli-service、vue-loader、sass、sass-loader，以及处理静态资源的url-loader或file-loader。这里我不建议手动去dependencies里逐条改，最稳的方式是从官方Vue3 webpack模板出发，把若依Vue3的src目录和路由权限逻辑拷进去，构建依赖保持模板原样，这样坑最少。
3. 本地跑通webpack版若依Vue3：从拉码到登录的最小步骤
3.1 环境准备与依赖安装
先把Node版本确认清楚。webpack5 + Vue CLI 5对Node的要求是12以上，但如果你要跑老一套的node-sass，Node版本最好锁在14或16，别一上来就上18或20，后者大概率会让node-sass编译直接挂掉。检查完版本后，把工程根目录下的package.json里scripts部分改成下面这样：
{ "scripts": { "dev": "vue-cli-service serve", "build:prod": "vue-cli-service build", "build:stage": "vue-cli-service build --mode staging" } }安装依赖时我建议用npm或pnpm都可以，但如果你在Windows上，注意别混用npm和yarn的lock文件，否则node_modules结构会乱掉，后面启动报一堆模块缺失时根本分不清是依赖问题还是配置问题。装依赖的命令很简单，在工程根目录执行：
npm install装完后先不急着启动，先在node_modules下确认webpack和vue-loader的版本，查看命令如下：
npx webpack --version npx vue-loader --version这里有个细节要说明：webpack5不再需要webpack-cli额外安装，Vue CLI 5内部直接集成了webpack5的构建链路；vue-loader如果版本是15.x，对应webpack4，如果是17.x及以上才是webpack5配套。看到这里大家应该能明白，为什么我总是强调先在node_modules里核对版本——很多webpack版若依Vue3跑不起来的头号原因，不是代码问题，而是构建工具链版本错配。
3.2 配置代理并启动前端
依赖安装好后，第二步是把vue.config.js里的devServer代理写好。这个文件在webpack版里是核心，前后端联调全靠它。下面这份配置是我最常用的基础版，适用于若依后端默认跑在localhost:8080的情况：
const { defineConfig } = require('@vue/cli-service') module.exports = defineConfig({ transpileDependencies: true, publicPath: process.env.NODE_ENV === 'production' ? '/' : '/', devServer: { port: 80, host: '0.0.0.0', proxy: { '/dev-api': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/dev-api': '' } } } } })这段配置的核心逻辑是：前端页面里所有以/dev-api开头的接口请求，都会转发到localhost:8080，并把路径前缀/dev-api去掉。如果你后端的接口前缀不是/dev-api而是/prod-api，把key和pathRewrite里的字符串同步改掉就行。这里有一个很容易忽略的点：target里如果写了http://localhost:8080，而后端入口是http://localhost:8080/xxx/api，那么pathRewrite要写成{ '^/dev-api': '/xxx/api' }，否则后端路由会找不到handler。
配置写好后，执行启动命令：
npm run dev看到Compiled successfully字样后，浏览器访问http://localhost，如果端口改成别的，就访问对应端口。我第一次跑通时，卡在了一个很蠢的地方：因为host写的是0.0.0.0，我以为要访问http://0.0.0.0，结果浏览器直接拒绝连接。后来才反应过来，本地访问直接用localhost就可以了，0.0.0.0是给局域网其他设备访问用的。
3.3 确认跑通的三条标准
跑通的判断标准不能只看页面有没有出来，我一般按三条逐项核对。第一条，浏览器地址栏输入访问地址后，页面能正常渲染出登录界面，说明前端静态资源加载没问题。第二条，在登录页点一下登录按钮，Network面板里能看到/dev-api/login这个请求、返回状态码不是404或500，说明代理起效了。第三条，登录成功后跳转首页、菜单能按权限加载出来，说明路由和动态权限逻辑在webpack的打包体系下工作正常。
如果第二条挂了，先看代理配置里的changeOrigin有没有写true。很多模拟项目X里后端做了Host校验，不设这个字段就会跳“非法请求”。如果是接口通但返回200却拿不到数据，大概率是pathRewrite写错了，前缀没删干净。这三条都过，基本可以放心往里面加业务页面了。
4. 必须改的vue.config.js：代理、publicPath、静态资源与构建体积
4.1 devServer代理与多环境切换
上一章写的代理是最简版，实际项目里往往会有多个环境：本地联调用localhost:8080，测试环境用http://某测试服务器，预发环境又是另一个域名。我一般会把这几个后端地址写进.env.development里，然后在vue.config.js里读取，避免每次换环境都去改配置文件。
const API_TARGET = process.env.VUE_APP_API_TARGET || 'http://localhost:8080' module.exports = defineConfig({ devServer: { port: 80, proxy: { '/dev-api': { target: API_TARGET, changeOrigin: true, pathRewrite: { '^/dev-api': '' } } } } })对应在.env.development文件里增加一行：
VUE_APP_API_TARGET=http://localhost:8080这样做的价值在于：换后端联调环境时，不需要动vue.config.js，只要改环境变量文件，而且这个文件一般不会误提交到生产构建里去。我见过太多团队在proxy里写死后端地址，然后测试环境联调时为了赶需求临时改掉，上线前又忘了改回来，结果生产环境的前端所有接口请求都往测试服务器打，这个问题在webpack版里尤其容易犯，因为vue.config.js默认就在工程根目录，手一快就改了。
再补充一个关于devServer.historyApiFallback的点。如果你在本地访问某个路由页面，刷新后直接变成404，十有八九是这个配置缺失。Vue CLI 5里默认会开，但如果你的devServer对象覆盖得太多，可能把它挤掉了。显式加一行比较保险：
historyApiFallback: true4.2 publicPath、静态资源目录与gzip
生产构建时遇到的最典型问题是：打包后的dist/index.html里，JS和CSS路径写死了/根路径，部署到服务器的一个子路径如https://某域名/admin下，所有静态资源全部404。解决办法就是设置publicPath。
module.exports = defineConfig({ publicPath: process.env.NODE_ENV === 'production' ? '/admin/' : '/' })这里有一个容易混淆的点：publicPath只影响打包时静态资源的引用前缀，不会改变前端路由的base路径。如果你既要让资源部署在/admin/下，又要让路由访问/admin/login，那你还需要在路由实例里设置createWebHistory('/admin/')，两个地方要一起改，否则会出现“页面能打开但刷新后资源找不到”的割裂状态。
静态资源的输出目录也可以按需调整。若依的默认配置是dist/static，如果你希望静态资源单独放一个域名下做CDN，可以在configureWebpack里这样设置：
configureWebpack: { output: { filename: 'js/[name].[contenthash:8].js', chunkFilename: 'js/[name].[contenthash:8].js' } }文件名带上contenthash是做缓存的标配，每次部署后旧浏览器能自动拉到新版本。如果觉得手写output太硬，也可以在chainWebpack里操作webpack的config对象，但对我来说，configureWebpack这种直接改对象的方式更好理解，也更好调试，毕竟webpack这层玄学少碰为妙。
4.3 移除vite残留配置，避免两套构建打架
webpack版和vite版最大的风险就是「工程里残留vite配置」。我见过一个某跨平台系统的实际案例，前端仓库里同时存在vite.config.js和vue.config.js，启动命令用的是npm run dev，结果是先走vite启动，报错后又切到webpack，中间各种依赖缺失，排查了整整一天才意识到是两套配置混在一个仓库里。
正确做法是：如果确定走webpack路线，就把vite.config.js、.vite目录、index.html里的<script type="module" src="/src/main.js">全部清理掉，只保留webpack入口public/index.html。另外，Vite版通常会在package.json里带"vite"依赖，如果工程不需要它，npm uninstall vite一并移除，免得后续npm install拉回一堆用不到的构建依赖。清理完后再跑一次npm run dev，基本就不会出现启动命令被抢的情况了。
5. webpack迁移避坑：5个真实能让你卡一下午的问题
5.1 现象：node-sass编译直接报错，报错信息里有gyp字样
原因：Node版本与node-sass版本不匹配，node-sass是C++插件，Node版本变了它就得重新编译，编译环境不对就直接失败。
解决：优先换用sass（dart-sass）替代node-sass，它是纯JS实现，不依赖编译工具链。操作方式是卸载node-sass、安装sass，再把代码里的@import写法尽量迁移到@use，因为新版sass对@import的兼容开始告警。如果因为某些老样式还依赖于node-sass的细节行为，那就把Node锁到14，用export NODE_OPTIONS=--max_old_space_size=4096提高编译内存再试。
5.2 现象：登录后跳转首页，页面刷新就404
原因：前端路由用的是HTML5 History模式，后端没有做重定向。开发环境里我没遇到这个问题是因为devServer自带了historyApiFallback，但生产环境Nginx不配置的话，刷新就是404。
解决：Nginx的location需要配置try_files $uri $uri/ /index.html;，这一步是所有History路由应用部署的必经之路。不要试图让后端去适配前端路由，前端能解决的事就自己解决。
5.3 现象：代码生成模块生成的前端页面在webpack里报「Cannot find module」
原因：若依的代码生成功能默认生成的是适配Vite的目录结构和依赖写法，如果你在建表后直接生成前端Vue文件，它可能引用了@/api/xxx里面不存在或者写法不同的工具函数，加上webpack对路径别名解析比Vite更严格，报错就出现了。
解决：生成后检查两个地方，一是src/api目录下对应接口文件里的请求方法是否基于项目统一的request封装，二是生成文件里有没有import.meta.env这类Vite专属全局变量。手动把这两处改成webpack版的process.env.VUE_APP_BASE_API写法，再重新跑启动命令，模块缺失的报错就会消失。
5.4 现象：代理地址通但接口始终401，登录验证码一直说错误
原因：验证码是后端会话里生成的，如果前端和后端不在同一个会话域，验证码校验就会失败。开发环境里最常见的原因是changeOrigin没开，导致后端看到请求的Host是localhost而不是目标服务器，会话无法建立。
解决：确认vue.config.js里changeOrigin: true已经写上。如果还不行，检查后端SecurityConfig里是否把/dev-api前缀也纳入了白名单，若依后端一般默认放行的是/captcha、/login、/register，如果有二次开发改过路径，要把本次请求的路径如实加到白名单里，我自己就犯过这个错，后端把登录接口路径改成/auth/login后忘了同步白名单，排查了两小时才发现是权限拦截。
5.5 现象：构建产物首屏加载要十几秒，静态资源里jpg、png体积巨大
原因：webpack默认不会对图片做压缩，图片体积大了直接拖慢首屏。其次是路由懒加载没有正确生效，所有页面打进了一个bundle里。
解决：在vue.config.js里为chainWebpack配置image-webpack-loader对图片做压缩，并检查路由写法是否都用了() => import('@/views/xxx')的懒加载形式。这两个地方改完，构建产物体积通常能降30%以上。如果还要再极致一点，就按下一章的方式做拆包。
6. 进阶验证：用一份Nginx配置玩转构建产物冒烟
webpack版的若依Vue3构建完成后，我建议不要直接扔给运维就完事，先在本地用一个临时Nginx把dist目录跑起来做冒烟。这一步能抓出很多开发环境发现不了的坑，尤其是publicPath和路由base的问题。
server { listen 8082; server_name localhost; root /path/to/your/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /admin/ { alias /path/to/your/dist/; try_files $uri $uri/ /admin/index.html; } location /dev-api/ { proxy_pass http://localhost:8080/; } }这份配置里，location /admin/这段是给部署在子路径场景用的冒烟验证，如果你把publicPath设成/admin/，那么启动这版Nginx后，访问http://localhost:8082/admin/时，页面、静态资源、路由都应该正常工作。如果这个路径能过，说明构建和部署之间的衔接没有大问题。
另一个进阶技巧是把登录页和主框架分别拆成独立包。若依这类后台系统，登录页其实很小，单独拆出来能让用户在弱网环境下更快看到登录界面。写法是修改src/router/index.js里的懒加载方式，把登录页路由的手写加载方式改成动态导入，同时按业务域拆分动态路由表。具体来说，你可以把系统管理、日志管理两组路由的component字段改成不同chunk的import，这样首屏只加载登录页和框架页的公共代码，进入系统后再拉各个模块的JS。这样改动不影响功能，但能明显提升首屏体验。
最后想说的是，webpack版本地开发和部署的经验，其实和Vite差别不大，核心就是记住「配置在vue.config.js、请求代理靠devServer、构建产物验证靠本地Nginx、环境变量走process.env」。我每次接手一个webpack版若依工程，都会先花10分钟把这三份文件看一遍——package.json的scripts、vue.config.js的devServer、.env.development的变量——看完了就基本能判断这个工程有没有隐藏坑。这个习惯帮我避了不少雷，希望也能帮到你。
本文还有配套的精品资源，点击获取
