IDEA中SpringBoot+Vue前后端分离项目的启动运行与联调指南

前后端分离的项目现在基本是 Java Web 开发的标配了SpringBoot 做后端接口Vue 做前端页面两边各跑各的端口通过 HTTP 请求通信。但很多新手拿到这种项目之后第一步就卡住了——不知道用 IDEA 怎么把前后端同时跑起来要么后端起不来要么前端装不上依赖折腾半天还在环境里打转。这篇文章我直接用实操的方式带你走一遍完整的流程怎么用 IDEA 导入并启动 SpringBoot 后端、怎么在 IDEA 里跑起 Vue 前端、怎么处理联调时的跨域和代理最后再把我这几年帮别人排查环境问题时遇到的高频坑一次性列出来。内容偏入门但也会把原理讲清楚适合刚接触前后端分离项目、或者常年用别人搭好的脚手架但从来没自己跑通过的同学。1. 项目整体设计与运行思路拆解1.1 前后端分离项目到底长什么样先说一个很多人没想明白的问题前后端分离项目在运行层面其实是两个完全独立的进程。后端 SpringBoot 项目打成一个 jar 包或者直接在 IDEA 里以 Spring Boot 方式运行内嵌 Tomcat 监听一个端口比如8080。前端 Vue 项目则是通过 Node.js 启动一个开发服务器dev server监听另一个端口比如5173或8081。两者互不干扰前端页面通过axios向后端发起请求后端返回 JSON 数据给前端渲染。所以在你开始动手之前心里得有一个清晰的图景后端IDEA 里运行的 SpringBoot 应用负责接口和数据端口记清楚。前端IDEA 里通过 Terminal 跑npm run dev启动的 Vue 服务负责页面和交互。浏览器访问的是前端地址前端再代你去请求后端接口。这个模型一旦建立起来后面遇到任何问题你都能快速定位是前端的问题还是后端的问题而不是一头雾水地在两个工程之间来回乱试。1.2 为什么选择用 IDEA 同时管理前后端有人习惯前端用 VSCode后端用 IDEA两个编辑器来回切。我不想评价这种方式但如果你手上已经装了 IDEA我真的建议你试试在 IDEA 里把前后端都管起来理由很实际第一IDEA 的 Terminal 面板直接开在项目目录下不用再单独开一个 CMD 或者 PowerShell。第二IDEA 可以同时引入多个项目窗口前端一个窗口、后端一个窗口左右分屏改完前端代码切到后端重启效率很高。第三IDEA 的插件生态很完善Vue 插件、JavaScript 语法支持都做得很好写前端代码的体验不比 VSCode 差多少。有人可能要问IDEA 做 Vue 开发会不会很卡实测下来如果你的电脑内存少于 16G确实会有一些负担。我的建议是IDEA 里同时开两个窗口前端依赖安装完一次之后IDEA 对node_modules目录要做排除索引不然首次打开会一直转圈。这个操作后面我会细说。1.3 跑通项目前必须确认的环境清单别急着导代码先花五分钟把环境检查完后面能省大量时间。环境项要求说明IDEA 版本2021.2 及以上社区版够用后端和前端都能跑JDK1.8 或 11 或 17具体看项目的pom.xml中java.version配置Maven3.6IDEA 自带 Maven也可以自己指定本地安装Node.js对应 Vue 版本Vue 2 建议 14.x/16.xVue 3 Vite 建议 16.x/18.xnpm/yarn/pnpm任选其一项目用了哪个包管理工具就用哪个不要混用MySQL/Redis按项目要求后端启动前如果连不上数据库通常直接启动失败这里最容易被忽略的是Node 版本。很多朋友拿到 Vue2 的老项目vue-cli 4 那种直接装了 Node 20 去跑结果一堆依赖编译报错。为什么因为老项目的 node-sass 或者一些原生模块发布时只支持较低的 Node 版本。遇到这种情况建议用 nvmNode Version Manager把 Node 版本切到项目推荐的版本别硬扛。我见过太多人卡在这一步花了一个小时排查最后只是 Node 版本不对。2. IDEA 导入 SpringBoot 后端项目的完整流程2.1 打开项目的正确姿势拿到一个前后端分离的压缩包先解压。你会看到里面一般有两个文件夹比如backend或server和frontend或web也可能叫cloud和vue名字不同但结构类似。打开 IDEA 的时候注意一个关键点不要直接打开最外层的总目录而是分别打开后端项目含pom.xml的目录作为一个 IDEA 窗口再单独用另一个 IDEA 窗口打开前端项目含package.json的目录。为什么因为 IDEA 对项目的识别核心是pom.xmlMaven 项目和.idea目录。你把总目录打开IDEA 虽然也能识别到 Maven 模块但经常会出现 Maven 模块加载不全、依赖索引混乱的情况。分开打开每个窗口干干净净各管各的后面操作起来非常简单。IDEA 打开项目的路径File - Open然后选中后端项目根目录IDEA 会自动识别pom.xml并把它当 Maven 项目加载。如果右下角弹出提示问你是否信任项目选择 Trust Project 即可。2.2 Maven 配置解决依赖下载慢和版本不匹配后端项目导入后IDEA 会自动开始解析 Maven 依赖。这里很多人会遇到第一个问题依赖下载特别慢或者干脆下载失败。先说原因。Maven 默认的中央仓库在国外国内网络环境下下载速度不稳定。解决办法很直接修改 Maven 的settings.xml把镜像源换成国内阿里云镜像。settings.xml位置一般在 Maven 安装目录下的conf文件夹里或者在用户目录下的.m2文件夹里。打开后找到mirrors节点添加如下配置mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror修改完成后在 IDEA 的File - Settings - Build, Execution, Deployment - Build Tools - Maven里把User settings file指向你修改过的settings.xml。这里有个小技巧IDEA 里 Maven 的Local repository显示路径时如果settings.xml里的本地仓库目录含中文IDEA 有时候会解析异常。建议把本地仓库目录设在类似D:\maven-repo这种纯英文路径下省心很多。Maven 配置好之后IDEA 右侧的 Maven 工具窗口会开始刷新依赖。等到所有依赖都显示没有红色波浪线说明依赖加载完成。2.3 JDK 版本统一最常见的启动报错来源依赖加载完之后先别急着启动。检查一下项目的 JDK 和语言级别是否一致。操作路径是File - Project Structure - Project Settings - Project。把SDK选成项目要求的 JDK 版本Language level对应选好。再到Modules里设置 Module SDK 为与项目一致的版本。这里有个亲身踩过的坑项目pom.xml里写的java.version是 8但本机默认 JDK 是 17。启动的时候经常报类似无法将 java.util.List 转换为 java.util.List的 Java 编译错误或者直接报module 读取包 xxx 时出错。实际上不是代码问题纯粹是编译用的 JDK 版本跟项目要求不一致。还有一种情况项目用的 SpringBoot 版本比较高比如 2.7.x 或 3.x需要 JDK 8 或 17。SpringBoot 3.x 目前要求 JDK 17 起步所以如果你用 JDK 8 去跑 SpringBoot 3.x 项目启动时候会直接告诉你Unsupported Java version。下载项目后先看一眼pom.xmlproperties java.version17/java.version /properties然后确认本机装了对应版本的 JDK。没装的话去 Oracle 官网或 Adoptium 下载安装然后在 IDEA 的 Project Structure 里Add SDK - JDK指向安装目录即可。2.4 配置 application.yml数据库和端口绝大多数后端项目都需要连数据库。打开src/main/resources/application.yml或application.properties你会看到类似这样的配置server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/mydb?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456如果你不确定数据库密码或库名需要先本地建好数据库一般项目里会有sql文件导入即可再把这里的url、username、password改成你自己的。否则后端能启动但一旦调用到数据库相关的接口就会报Communications link failure或者Access denied for user。千万别忽略这一步很多人的后端报错并不是代码问题而是数据库连接信息没改。另外检查一下端口 8080 是否被占用。启动后如果报Port 8080 was already in use说明你的电脑上已经有一个程序占用了 8080。Windows 下可以用netstat -ano | findstr 8080查看占用进程的 PID然后在任务管理器里结束它或者直接把项目的server.port改成其他端口比如 8081。2.5 启动后端确认第一个接口能通所有配置完成后找到启动类。它一般在src/main/java下类名形如XxxApplication上面标着SpringBootApplication注解。右键这个类选择Run XxxApplication看底部控制台输出。正常的启动日志结尾会看到类似这样的内容Started XxxApplication in 5.23 seconds (JVM running for 6.01)看到Started说明后端启动成功。浏览器里直接访问http://localhost:8080/如果项目里配了欢迎页或swagger-ui能直接看到页面如果没有可能显示 404这不用慌因为项目默认没有暴露根路径的接口。你可以找一个接口试一下比如http://localhost:8080/api/hello能返回 JSON 数据就算通了。如果后端启动时报错按这段的经验先排查数据库连接、端口占用、JDK 版本。百分之八十的启动失败问题都出在这三块。3. IDEA 运行 Vue 前端项目的实操步骤3.1 Node.js 环境装对版本等于成功一半后端跑通之后打开另一个 IDEA 窗口导入前端项目。前端项目根目录的特征是有一个package.json文件。导入之后先别急着点运行先检查 Node.js 环境。命令行输入node -v npm -v如果提示找不到命令说明 Node.js 没装或者没配环境变量。推荐直接用 nvm 安装和管理 Node 版本。Windows 用户去 nvm-windows 的 GitHub 仓库下载安装包macOS/Linux 用户用 curl 安装。nvm 装好之后nvm install 16.20.2 nvm use 16.20.2这里选 16.20.2 是给 Vue 2 vue-cli 项目用的。如果项目是 Vue 3 ViteNode 16 也兼容Node 18 当然也行。关键在于如果项目里有node-sass依赖直接上 Node 18 大概率会编译失败。解决办法要么用 nvm 切到低版本要么把node-sass替换成sass这个改动会涉及代码里scss的引入方式新手不建议折腾。Node 确认没问题之后打开 IDEA 里的 Terminal 面板底部工具栏可以直接打开默认就在项目的当前目录执行依赖安装命令npm install如果项目里有package-lock.json或yarn.lock优先使用对应的命令npm ci或者yarn install。npm ci的好处是严格按 lock 文件的版本安装不产生版本浮动安装速度也更快。有个细节要提醒安装依赖的时候IDEA 会扫描node_modules目录可能导致电脑风扇狂转。解决办法是等npm install执行完毕后右键node_modules目录Mark Directory as - Excluded对应的中文界面是“排除”即可。IDEA 就不会再全量索引这个目录了。3.2 安装依赖失败的经典排错思路依赖安装是前端项目第一个大坎。常见报错大概有这几类第一类ENOSPC或EACCES文件权限问题。Windows 下一般是杀毒软件或安全策略锁了新文件macOS/Linux 下一般是运行用户权限不够。用管理员模式重新打开终端或者改用 sudo 执行仅限 macOS/Linux可以解决。第二类node-sass相关报错比如Module build failed: Error: ENOENT。这种几乎可以断定是 Node 版本不兼容。先看package.json里 node-sass 的版本要求再对应切 Node 版本。node-sass 4.x 对应 Node 14node-sass 6.x 对应 Node 16node-sass 7.x 对应 Node 16/18。再往上就是 Node 18 了能支持 Node 20 的场景很少。第三类网络超时。npm 默认源在国外安装大依赖的时候经常卡死。镜像源设置一劳永逸npm config set registry https://registry.npmmirror.com设置完之后重新npm install速度体感提升明显。3.3 在 IDEA 里配置 npm 启动脚本依赖装完之后打开package.json看scripts节点scripts: { dev: vue-cli-service serve, build: vue-cli-service build }如果是 Vite 项目会是scripts: { dev: vite, build: vite build }这段脚本决定了你用什么命令启动前端服务。dev 对应开发环境build 对应生产环境打包。在 IDEA 里运行其实很简单Terminal 里输入npm run dev输入后回车就看到 vite 或 webpack 的启动日志。等日志中显示VITE v4.5.0 ready in 3000 ms ➜ Local: http: //localhost:5173/打开浏览器访问http://localhost:5173/看到前端页面说明前端跑起来了。如果每次输入命令麻烦IDEA 里可以在package.json的面板左侧点一下dev左边的三角形箭头IDEA 会帮你一键运行。运行配置可以在Run/Debug Configurations里看到。3.4 前端启动后页面空白或请求报错怎么办前端服务正常启动但页面打开是一片空白这个现象也极其常见。打开浏览器的开发者工具F12看 Console 面板里的报错信息。如果报错是Failed to load resource: 404说明前端页面的路由没配置对。Vue 3 Vite 项目里如果没有配置history模式下的 fallback刷新子路由页面就会 404。开发模式下可以暂时不处理或者让后端配一下前端 history 回退。如果报错是TypeError: Cannot read properties of undefined (reading xxx)这个往往是接口返回的数据格式和页面预期不一致。先看 Network 面板里的接口返回再对代码。但最常遇到的是跨域报错Access to XMLHttpRequest at http://localhost:8080/api from origin http://localhost:5173 has been blocked by CORS policy。这个我在下一章专门展开讲。4. 前后端联调打通跨域和代理的关键环节4.1 跨域问题的本质前端跑在5173后端跑在8080前端页面向后端接口发请求浏览器会告诉你跨域了。跨域的本质是浏览器的同源策略。同源的意思是“协议 域名 端口”三者完全一致。前端和后端端口不同所以不同源浏览器默认会拦截前端发出的 ajax 请求。这是浏览器的安全机制不是后端接口挂了也不是前端代码错了。跨域问题在开发模式和生产环境下的解决方式不同需要区分。4.2 方案一后端开启 CORS后端解决跨域最简单的方式是用CrossOrigin注解注解在 Controller 类或方法上CrossOrigin(origins http://localhost:5173) RestController RequestMapping(/api) public class UserController { }表示允许来自http://localhost:5173的请求访问。如果项目里有很多 Controller每个都加注解很麻烦。更好的做法是全局配置实习做一个配置类Configuration public class CorsConfig { Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }; } }注意allowCredentials(true)与allowedOriginPatterns(*)搭配时不能使用allowedOrigins(*)否则部分浏览器会报错。这是个容易踩的细节。后端开了 CORS 之后前端直接请求后端接口就能通。但实际开发中很多项目默认不开 CORS因为生产环境里前后端通常部署在同一个域名下开 CORS 反而有安全风险。所以更优雅的方式是前端代理。4.3 方案二前端 devServer 代理Vue CLI 项目里配置在vue.config.jsmodule.exports { devServer: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }Vite 项目里配置在vite.config.jsexport default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })配置完成之后前端代码里请求地址写/api/user/list浏览器发出的请求落在前端服务器上前端服务器再转发给http://localhost:8080/api/user/list。由于服务端之间的请求不受浏览器同源策略的限制跨域问题就消失了。这里要记住一个区别前端代理只在开发模式下生效生产环境部署时不会经过 devServer。所以生产环境要么后端开 CORS要么通过 Nginx 把前后端配置在同一个域名路径下。顺带一提前端请求地址写全路径还是写相对路径直接决定代理能否生效。如果代码里写的是http://localhost:8080/api/user/list代理配置就起作用了因为请求直接发给了后端。想让代理生效前端代码里的统一请求基础路径必须是相对路径比如/api。4.4 联调验证从登录页到列表页配置完代理或 CORS 之后重启前端服务再登录页面测试。建议按这个顺序验证打开浏览器开发者工具的 Network 面板刷新页面。看所有请求的 URL如果前缀是http://localhost:5173/api/...说明代理正在转发。点击任意一条请求看响应。正常返回 JSON 数据状态码 200。如果有 404先看后端接口路径和前端请求路径是否一致如果有 500问题在后端看后端控制台堆栈。如果登录能通但页面数据为空检查后端返回的数据结构和前端页面的字段是否匹配。我一般联调时习惯把浏览器前后端控制台同时打开浏览器看请求状态IDEA 后端控制台看日志输出。两边对照着看问题会很快定位。5. 常见问题与排查技巧实录5.1 端口占用问题速查报错信息原因解决方案Port 8080 was already in use8080 被其他进程占用Windows 执行 netstat -anoPort 5173 was already in useVite 默认端口被占用在vite.config.js里改server.portError: listen EADDRINUSENode 服务端口被占结束占用进程或换端口提示IDEA 底部有一个 “Services” 窗口里面能看到当前启动的所有服务和端口。如果同一个端口启动了多个实例最后启动的那个会失败先停掉旧的再启动新的。5.2 后端启动报错汇总后端启动失败的报错五花八门但其中 90% 集中在以下几类第一Failed to configure a DataSource。项目引入的spring-boot-starter-data-jpa或mybatis自动配置需要数据源但你没配数据库。要么在application.yml里补上数据源配置要么在启动类上排除数据源自动配置SpringBootApplication(exclude {DataSourceAutoConfiguration.class})第二种ClassNotFoundException: org.springframework.boot.context.properties.bind.Bindable。SpringBoot 版本和依赖版本不匹配尤其常见于某些第三方 starter 的版本引用了不兼容的 SpringBoot 版本。排查pom.xml尽量用与 SpringBoot 版本配套的 starter。第三种lombok报错java: 找不到符号 变量 log或getter 方法找不到。原因大概率是 IDEA 没有启用注解处理器或者 Lombok 插件未安装。打开Settings - Build, Execution, Deployment - Compiler - Annotation Processors勾选Enable annotation processing再安装 Lombok 插件。IDEA 2020.3 之后的版本已经内置 Lombok 插件新版本基本不用装。5.3 前端启动报错汇总前端项目比后端更依赖环境因为 Node 生态的变数实在太多了。第一种Error: Cannot find module webpack。依赖没装全。删除node_modules目录和package-lock.json重新执行npm install。注意要用项目原有的包管理工具不要 npm 和 yarn 混用。第二种Syntax Error: TypeError: this.getOptions is not a function。sass-loader 版本和 sass 版本不兼容一般是 sass-loader 版本与 Webpack 版本冲突。Vue CLI 项目里建议固定 sass-loader 的版本为 10.x 左右不要用最新的 sass-loader它要求 Webpack 5。第三种Unhandled error during execution of render function或编译时报Module not found。通常是某个 npm 包没装成功或者包版本和项目要求的版本不一致。在package.json里查一下这个包的引用位置然后单独重新安装npm install 包名 --save-dev第四种npm install时出现npm ERR! code ELIFECYCLE。一般是某个依赖包的 postinstall 脚本执行失败。常见于node-sass或sharp这类需要二进制编译的包。解决方案是切换 Node 版本或更换镜像源。5.4 数据接口通了但页面渲染异常联调时如果接口返回 200但页面表格无数据或者样式错乱排查思路要转变——这不是环境问题大概率是代码或数据处理问题。一般先看 Console 里的 Vue 报错再对照接口返回的字段名和页面代码里的字段名最常见的坑是后端返回userName前端写的是name数据对不上最后看是不是数据层级问题比如接口返回的是{ code: 200, data: { list: [] } }前端取的是res.data.records自然会取不到。这种问题我之前也遇到过建议联调时开发工具里打开 Network点接口详情看 Response 原始数据对照代码里的赋值逻辑基本几分钟就能定位。5.5 打包部署的进一步扩展跑通开发环境只是第一步真实项目上线时前后端还是有不同的构建和部署方式。后端打包很简单在 IDEA 右边 Maven 面板里执行package命令或者mvn clean package -DskipTests构建后在target目录下得到xxx.jar。运行java -jar xxx.jar前端打包执行npm run buildVite 构建产物一般在dist目录把整个目录放到 Nginx 的html目录下即可。生产环境的跨域问题更多是通过 Nginx 反向代理解决的一个典型的 Nginx 配置是这样的server { listen 80; server_name your-domain.com; location / { root /usr/share/nginx/html; index index.html index.htm; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://localhost:8080/api/; } }这个配置的含义前端页面由 Nginx 托管访问/api/的请求转发到后端的 8080 端口。这样前后端在同一个域下自然不存在跨域问题。6. 写在最后的实战心得我在带新人或者帮朋友调试项目时发现一个共性现象大多数跑不起来的问题根源都是“环境不一致”而不是“代码有问题”。IDEA 里的 JDK 版本、Maven 的镜像源、Node.js 的版本、数据库的账号密码任何一个环节和项目预期的不匹配都会导致全过程看起来像是出 bug 了其实只是环境不对。所以我在实际操作中的习惯是拿到一个新项目第一件事不是点运行而是先花十分钟把下面几个信息确认齐pom.xml里要求的 Java 版本package.json里要求的 Node 版本application.yml里的数据库和端口配置前端开发服务器代理的后端地址。这些信息都核对清楚之后再开始运行基本能做到一遍过。最后再分享一个小技巧IDEA 里打开多个项目窗口之后可以把每个窗口的代码折叠区域都用不同的颜色 Theme 区分比如后端用默认的 Darcula前端用浅色主题这样切换的时候不容易走神。更重要的是经常给项目写一个简短的README把启动步骤、默认端口、数据库初始化语句这些信息记下来下次再看这个项目或者换台电脑继续开发时不需要重新摸索一遍。好记性不如烂笔头这在前后端联调领域里是省时省力的最佳实践。