环境搭建与第一个 Web 应用

这是什么：第一个 Spring Boot 应用 = 从零生成一个 Web 项目并跑起来，全程不用手写一行配置代码。

为什么用：上一章认识了 Spring Boot 这位「管家」，可光认得它没用，得真把它请上岗。这一章让你亲眼看到：不写配置文件，一个能访问的 Web 应用就跑起来了。

如何用：本章从确认 JDK、到 start.spring.io 生成项目、再到解压运行和访问页面，四步走完一个完整项目。

版本说明：本系列基于 JDK 25 LTS + Spring Boot 3.x（start.spring.io 默认最新版）。界面会随版本微调，认准按钮和选项名就行。

第一步：确认 JDK

Spring Boot 跑在 Java 上，先确认装了 JDK（推荐 JDK 21 及以上，推荐 25 LTS）。命令行输入：

java -version

你会看到类似输出：

java version "25" 2025-09-16 LTS
Java(TM) SE Runtime Environment ...

能看到版本号就绪；没装的话去 Adoptium 下载安装，装完重开命令行再试。

顺带分清三个长得很像的词：

跑网站需要的是能写代码、能编译的 JDK，装它准没错。

第二步：start.spring.io 生成项目

手建 Spring Boot 项目要写不少配置文件，官方提供了"项目生成器"：打开 start.spring.io，像点快餐一样勾选项，它替你把项目骨架配好打包。按下面选：

关键一步：点右侧 ADD DEPENDENCIES，勾选 Spring Web——这是让项目具备 Web 能力的开关。最后点 GENERATE，会下载一个 zip 压缩包。

几个选项别看着发怵，都是纸老虎：

其实每个选项背后都对应 pom.xml（依赖清单文件）里的一两行——生成器干的活，本质是"替你写配置文件"。

第三步：解压并运行

解压后是一个完整项目。不用装 Maven——项目自带 mvnw（Maven wrapper），它会自动下载该用的一切。

mvnw 好比"随项目附赠的说明书翻译机"：项目需要哪个版本的 Maven、按什么清单下载零件，它都自带答案。所以别人拿到你的项目，也不用装任何东西就能跑——团队协作、交给导师检查都省心。

两种方式任选其一：

• IDE 方式：用 IntelliJ IDEA（社区版免费）Open 解压出的文件夹，等右下角依赖下载完，运行 DemoApplication 里的 main 方法。判断"打开对了"的标志：IDEA 左侧能看到 pom.xml，且没标红——第一次打开会有一段"Importing / Downloading"的等待，属正常现象
• 命令行方式：在项目文件夹的地址栏输入 cmd 回车，执行：

mvnw spring-boot:run

（macOS / Linux 用户前面加 ./，写作 ./mvnw spring-boot:run）

首次运行要下载大量依赖，耐心等几分钟。看到这样的日志就成功了（示意）：

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.x.x)

... Tomcat started on port 8080 (http) ...
... Started DemoApplication in 3.2 seconds ...

第四步：访问看看

浏览器打开 http://localhost:8080——看到的是一个黄底白字的 Whitelabel Error Page。

别慌，这恰恰说明成功：报错是因为我们还没写任何内容，但这个报错页面本身是内嵌 Tomcat 发出来的——服务器已经在 8080 端口站好岗了。按 Ctrl + C 可随时停掉应用。

localhost 就是"本机"的意思——你的电脑自己扮演了服务器和访客两个角色；8080 是端口号，相当于这栋"服务器大楼"上开着的窗口号。两个词合起来："去本机的 8080 号窗口敲门"。

再交个朋友：把这个地址发给同一间屋子里的另一台电脑，是打不开的——服务器跑在你机器上，别人才进不来。将来真要"上线"，就是把项目部署到云服务器上，那是后话；现阶段 localhost 就是我们全部的世界，效率还最高。

生成的项目里都有什么

跑通之后别急着翻篇，打开项目文件夹看看骨架长什么样：

demo/
├─ mvnw · mvnw.cmd          ← Maven wrapper（Windows 用 .cmd，Mac/Linux 用无后缀版）
├─ pom.xml                  ← 依赖清单：声明"这个项目要用哪些零件"
└─ src/
   ├─ main/java/com/example/demo/
   │  └─ DemoApplication.java   ← 启动类，整个应用的点火开关
   └─ main/resources/
      ├─ application.properties ← 配置文件：端口号、各种开关都写这
      ├─ static/                ← 放静态文件（图片、CSS、直接可访问的 html）
      └─ templates/             ← 放页面模板（后面 Thymeleaf 章节的主场）

最值得看一眼的是启动类，一共没几行：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

注意类放在 com.example.demo 包里——@SpringBootApplication 默认只扫描这个包及子包，以后新建的控制器都得放它底下（或子包里），放外面框架就"看不见"了。这是新手后期最常见的"代码没生效"悬案，现在先埋个伏笔。

这一章发生了什么

表面上看只是"点了几下、跑了一条命令"，背后的事一件没少干。把每一步的里子掀开看看：

启动日志也值得会读，三行关键信息：

📝 本章小结

• 环境三步走：确认 JDK → start.spring.io 勾 Spring Web 生成项目 → mvnw spring-boot:run 跑起来
• pom.xml 是依赖清单，生成器替你写好；mvnw 让任何人拿到项目都能跑，不用装 Maven
• localhost:8080 = 本机 8080 号窗口；见到 Whitelabel 报错页恰恰说明服务器活了
• 启动类是点火开关，@SpringBootApplication 只扫描本包及子包——新代码要放对地方
• 改代码必重启；换实验先 Ctrl + C；命令行认准"看得见 pom.xml 的目录"
• 记忆口诀：生成项目去官网，Web 依赖勾上先；wrapper 一跑不用装，8080 见页即上线。

❓ 常见问题

Q1：启动报 Port 8080 was already in use 怎么办？

端口被占了——多半是上一个应用没停干净，或别的程序占着 8080。最快的解法：改用别的端口。在 application.properties 里写一行 server.port=9090，重启应用访问 9090 就行（这招在"动手改"第 1 题里会让你正式练一遍）。

Q2：命令行提示 'mvnw' 不是内部或外部命令？

十个有九个是目录不对：mvnw 在项目根文件夹里，必须站在这个文件夹里执行才找得到。地址栏输入 cmd 回车，天然就在当前文件夹，推荐这个方式；Mac/Linux 记得写成 ./mvnw。

Q3：首次运行卡在下载依赖，一动不动？

首次运行要下载几十兆依赖，几分钟属正常，别手欠按 Ctrl+C。真超时报错的话，九成是网络问题——重跑一次 mvnw spring-boot:run 通常就能续上；企业里还会给 Maven 配国内镜像加速，入门阶段先重试即可。

Q4：java -version 提示"不是内部或外部命令"？

JDK 没装好或没加进 PATH。装完 JDK 必须重开一个命令行窗口（老窗口不会刷新环境变量）；还不行就去系统环境变量里检查 PATH 有没有 JDK 的 bin 目录。

⚠️ 新手翻车现场

翻车一：改了代码，刷新页面没反应

Spring Boot 不会自动重新编译——main 一跑起来就是"已定格"的版本。改动 Java 代码后，必须 Ctrl + C 停掉再 mvnw spring-boot:run 重启。前期请养成"改完就重启"的肌肉记忆，能省掉九成"灵异事件"。

翻车二：把项目文件夹套了一层又一层

解压时选了"解压到 demo\"，又手动拖了一层文件夹，结果在错误的目录里运行 mvnw，报"找不到 pom.xml"。判定标准：运行命令的目录里必须直接看得见 pom.xml 和 mvnw。

翻车三：8080 端口被自己上一个实验占着

上一次的命令行窗口没关，应用还挂着，新应用起不来。规矩：一个窗口跑一个应用，换实验前先 Ctrl + C 把旧的停掉。

三个翻车殊途同归，指向同一个道理：开发环境是有状态的世界——哪个窗口开着、站在哪个目录、上次起没停，都会影响下一次操作。把这些"环境状态"管理好，是比写代码更早要养成的习惯，越早养成越省心。

记忆口诀

生成项目去官网，Web 依赖勾上先；wrapper 一跑不用装，8080 见页即上线。

动手改

都是"改一行配置 / 放一个文件"级别的小活，做完你对项目的掌控感会翻倍：

1. 在 src/main/resources/application.properties 里加一行 server.port=9090，重启后访问 http://localhost:9090 试试
2. 在 src/main/resources/static/ 文件夹（没有就新建）放一个 index.html，写上 <h1>我的第一个页面</h1>，重启后访问 http://localhost:8080——静态页面直接就能访问！
3. 把生成页面的 Group 改成自己名字的拼音，重新生成一个项目，对比两份 pom.xml 有什么变化

下一章：控制器与路由，让 8080 端口说出你的话 🐸