Java Snowy v3.6.2 前后端本地环境搭建全流程（踩坑实录）

作者笔记：本文记录了在 macOS 环境下，从零搭建 Snowy（小诺）v3.6.2 前后端项目的完整过程。我在 Maven 依赖下载环节遇到了连续多个坑，最终一一解决。希望这篇踩坑记录能帮到同样在折腾 Snowy 的朋友。

感谢 WorkBuddy AI 对本次踩坑过程提供了诸多解决方案。

项目简介

Snowy 是目前国内非常热门的Java开发的前后端分离快速开发平台，基于以下技术栈：

层面	技术
后端	SpringBoot 3.5 + MyBatis-Plus + Sa-Token + HuTool
前端	Vue 3 + Ant Design Vue 4 + Vite 5
数据库	MySQL 8.0 / PostgreSQL / 达梦 / 人大金仓等
缓存	Redis
特色	国密算法（SM2/SM3/SM4）、多租户、代码生成、工作流等

项目地址：https://gitee.com/xiaonuobase/snowy （Star 33K+）

源码获取

# 由于团队项目需求，这里克隆指定版本的源码
git clone https://gitee.com/xiaonuobase/snowy.git
cd snowy
git checkout v3.6.2

克隆完成后，项目结构如下：

snowy/
├── snowy-admin-web/          # 前端工程（Vue3 + AntDesignVue4）
├── snowy-common/             # 基础通用模块
├── snowy-plugin-api/         # 插件 API 接口层
│   ├── snowy-plugin-auth-api/
│   ├── snowy-plugin-sys-api/
│   └── ...
├── snowy-plugin/             # 功能插件实现层
│   ├── snowy-plugin-auth/    # 登录鉴权
│   ├── snowy-plugin-sys/     # 系统管理
│   ├── snowy-plugin-dev/     # 开发工具
│   └── ...（共7个子模块）
├── snowy-web-app/            # 后端启动入口（主模块）
└── pom.xml                   # Maven 父 POM

核心要点：snowy-web-app 是后端的启动入口，snowy-admin-web 是前端工程。

---

开发环境要求

整体架构一览

后端环境

组件	版本要求	本文使用版本
JDK	17+	Amazon Corretto 21.0.10**（项目要求 17+）
Maven	最新版	IDEA 内置 Maven
MySQL	8.0 / 5.7	MySQL Community 8.0.36
Redis	最新版	Redis 8.2.2
IDE	IntelliJ IDEA	2024.x+

前端环境

组件	版本要求	说明
Node.js	18+	推荐 20 LTS
包管理器	npm / pnpm / yarn	随意
IDE	VSCode / WebStorm	随意

renxing@bogon ~ % java -version
openjdk version "21.0.10" 2026-01-20 LTS
OpenJDK Runtime Environment Corretto-21.0.10.7.1 (build 21.0.10+7-LTS)
OpenJDK 64-Bit Server VM Corretto-21.0.10.7.1 (build 21.0.10+7-LTS, mixed mode, sharing)
renxing@bogon ~ %
renxing@bogon ~ % mvn -v
Apache Maven 3.9.2 (c9616018c7a021c1c39be70fb2843d6f5f9b8a1c)
Maven home: /Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3
Java version: 21.0.10, vendor: Amazon.com Inc., runtime: /Users/renxing/Library/Java/JavaVirtualMachines/corretto-21.0.10/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "14.4.1", arch: "aarch64", family: "mac"
renxing@bogon ~ %
renxing@bogon ~ % mysql -V
mysql  Ver 8.0.36 for macos14 on arm64 (MySQL Community Server - GPL)
renxing@bogon ~ %
renxing@bogon ~ % redis-server -v
Redis server v=8.2.2 sha=00000000:1 malloc=libc bits=64 build=b8c0c59a9db96eb1
renxing@bogon ~ %
renxing@bogon ~ % node -v
v20.19.5
renxing@bogon ~ %
renxing@bogon ~ % npm -v
10.8.2

---

后端搭建步骤

步骤 1：用 IDEA 打开后端项目

1. 打开 IntelliJ IDEA
2. 菜单栏 File → Open
3. 选择 snowy 项目根目录
4. 等待 IDEA 索引和导入项目

我的项目源代码路径：/Users/renxing/code/java/snowy

用 IDEA 打开 snowy 项目后，pom.xml 中大量依赖飘红。右侧 Maven 面板点击刷新按钮后，报出如下错误：

org.springframework.boot:spring-boot-starter-parent:pom:3.5.9 failed to transfer 
from https://repo.maven.apache.org/maven2 during a previous attempt. 

Original error: Could not transfer artifact org.springframework.boot:
spring-boot-starter-parent:pom:3.5.9 from/to central 
(https://repo.maven.apache.org/maven2): Remote host terminated the handshake

关键信息解读：

• 错误来源：repo.maven.apache.org/maven2（Maven 中央仓库）
• 错误类型：Remote host terminated the handshake（SSL 握手被中断）
• 我已经 clone 了最新源码，说明代码本身没问题，纯粹是依赖下载失败

步骤 2：配置 Maven 镜像源（国内必须！）

⚠️ 这是第一个大坑！

由于 Maven 中央仓库（repo.maven.apache.org）在国外，国内访问经常超时或 SSL 握手失败。因此：必须在 IDEA 中配置国内镜像源。

具体操作：Cmd + , 打开 IDEA 设置，搜索 Maven → 进入 Build Tools → Maven，找到 User settings file → 点击 Override → 点击右侧的文件夹图标：

打开 Maven 配置文件 ~/.m2/settings.xml（如果没有就新建），写入以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
    
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <mirrorOf>*</mirrorOf>
            <name>阿里云公共仓库</name>
            <url>http://maven.aliyun.com/repository/public</url>
        </mirror>
    </mirrors>

</settings>

💡 注意两点：

1. 这里用的是 HTTP 不是 HTTPS（后面会解释为什么）
2. <settings> 标签必须有，不能只写 <mirrors>

步骤 3：点击 Maven 刷新 → 踩坑开始

点击 IDEA 右侧 Maven 面板顶部的刷新按钮 🔄，然后……

踩坑 1：SSL 握手失败

报错信息：

Could not transfer artifact org.springframework.boot:spring-boot-starter-parent:pom:3.5.9 
from/to central (https://repo.maven.apache.org/maven2): Remote host terminated the handshake

原因分析：即使配置了镜像，Maven 在某些情况下仍会尝试连接中央仓库。而 macOS + JDK 21 的环境下，HTTPS 连接国外服务器极易出现 SSL 握手被中断的情况。

解决方案 A — 清除失败缓存：

Maven 会把失败的下载记录缓存为 .lastUpdated 文件，导致后续不再重试。必须删除它们：

# 删除所有失败的缓存记录
find ~/.m2/repository -name "*.lastUpdated" -delete && echo "清理完成"

解决方案 B — 设置 JVM SSL 放宽参数：

在 IDEA 中进入 Build, Execution, Deployment → Build Tools → Maven → Importing（注意是 Importing，不是 Runner！）：

找到 VM options for importer，填入（一行输入，不要换行）：

-Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true

这三个参数的作用：

• ssl.insecure=true：允许不安全的 SSL 连接
• ssl.allowall=true：接受所有证书
• ssl.ignore.validity.dates=true：忽略证书日期校验

⚠️ 重要提醒：很多人把这个参数加到了 Runner 标签页里，但 Runner 只影响执行 mvn run/test，不影响 Maven Import 刷新依赖！一定要加在 Importing 里！

解决方案 C — 镜像改用 HTTP 协议（最彻底）：

如果以上方法还不行，直接把镜像从 HTTPS 改为 HTTP，彻底绕过 SSL 问题：

<mirror>
    <id>aliyun</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>http://maven.aliyun.com/repository/public</url>   <!-- 注意这里是 http -->
</mirror>

踩坑 2：命令行 mvn 找不到

如果想在终端用 mvn 命令快速构建，但系统没有安装独立的 Maven，可以复用 IDEA 内置的。

在 ~/.zshrc 中添加别名（注意路径中的空格要转义）：

alias mvn="/Applications/IntelliJ\ IDEA.app/Contents/plugins/maven/lib/maven3/bin/mvn"

然后 source ~/.zshrc 生效即可，以后直接输入 mvn 就可以了。

也可以把 MAVEN_OPTS 写入 .zshrc 一劳永逸：

export MAVEN_OPTS="-Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true"

踩坑 3：BUILD FAILURE — 找不到 snowy-common:jar

报错信息：

Could not find artifact vip.xiaonuo:snowy-common:jar:3.0.0 in tencent

原因：dependency:resolve 只能解析外部依赖，而 snowy-common 是项目自己的内部模块，需要先编译安装到本地仓库。

解决：使用 install 命令代替：

mvn clean install -DskipTests -f /Users/renxing/code/java/snowy/pom.xml

这条命令会按顺序编译所有 21 个模块并安装到本地 Maven 仓库（~/.m2/repository），后续模块就能找到前面的依赖了。

构建成功

踩完了上面的坑，接下来应该就没啥问题了。继续执行：

cd /Users/renxing/code/java/snowy && mvn clean install -DskipTests

首次构建可能需要 3~10 分钟，看到 BUILD SUCCESS 就说明全部成功。

[INFO] Reactor Summary for snowy 3.0.0:
[INFO] snowy .............................................. SUCCESS
[INFO] snowy-common ....................................... SUCCESS  [35.093 s]
[INFO] snowy-plugin-api ................................... SUCCESS
[INFO] snowy-plugin-auth-api .............................. SUCCESS
[INFO] snowy-plugin-sys-api ............................... SUCCESS
[INFO] ...（共21个模块，全部SUCCESS）
[INFO] snowy-web-app ...................................... SUCCESS  [25.851 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] Total time: 02:55 min

21 个模块全部编译成功，BUILD SUCCESS！

步骤 4：启用 Lombok 注解处理

项目启动后，IDEA 右下角可能弹出提示：

Lombok requires enabled annotation processing

解决方法：

1. 直接点击提示框中的 「Enable annotation processing」 按钮
2. 或手动操作：Settings → Build, Execution, Deployment → Compiler → Annotation Processors → 勾选 Enable annotation processing

不启用的话，项目中大量使用的 @Data、@Getter、@Slf4j 等 Lombok 注解都不会生效，代码会一片红色。

---

数据库初始化

Snowy 的 SQL 初始化脚本位于：

snowy-web-app/src/main/resources/_sql/snowy_mysql.sql

创建数据库并导入

# 1. 创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS snowy DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

# 2. 导入表结构和初始数据（约 220KB，包含几十张表）
mysql -u root -p snowy < /path/to/snowy/snowy-web-app/src/main/resources/_sql/snowy_mysql.sql

# 3. 验证
mysql -u root -p -e "USE snowy; SELECT COUNT(*) AS table_count FROM information_schema.tables WHERE table_schema='snowy';"

数据库配置说明

默认的数据库连接配置在 snowy-web-app/src/main/resources/application.properties 中：

# 数据库连接
spring.datasource.dynamic.datasource.master.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.dynamic.datasource.master.url=jdbc:mysql://localhost:3306/snowy?...
spring.datasource.dynamic.datasource.master.username=root
spring.datasource.dynamic.datasource.master.password=12345678

# Redis 连接
spring.data.redis.host=127.0.0.1
spring.data.redis.port=6379
spring.data.redis.password=
spring.data.redis.database=1

# 服务端口
server.port=82

如果你的 MySQL 密码不是 12345678，记得修改 application.properties 第 28 行的密码。

Redis 启动

确保 Redis 服务正在运行：

# 启动 Redis（守护进程方式）
redis-server --daemonize yes

# 验证是否运行中
redis-cli ping
# 返回 PONG 表示正常

Snowy 使用了两个 Redis database：

• database=1：业务数据缓存
• database=2：Sa-Token 权限认证缓存

---

启动后端项目

一切准备就绪后，在 IDEA 中启动项目：

1. 在项目树中展开 snowy-web-app → src → main → java → vip.xiaonuo
2. 找到 Application.java（带有 @SpringBootApplication 注解的主类）
3. 右键 → Run ‘Application’
4. 控制台看到以下输出即启动成功：

----------------------------------------------------------
Application is running! Access URLs:
Local:    http://localhost:82
Doc:      http://localhost:82/doc.html
----------------------------------------------------------

此时可以访问：

• 后端接口：http://localhost:82

• API 文档（Knife4j）：http://localhost:82/doc.html

  用户名：admin，密码：123456

• Druid 监控台：http://localhost:82/druid/

  用户名：admin，密码：123456

---

前端搭建步骤

步骤 1：安装 Node.js 依赖

进入前端目录：

cd snowy-admin-web

# 安装依赖（推荐使用 pnpm 或 npm）
pnpm install
# 或者
npm install

💡 如果网络慢，可以设置淘宝镜像：

npm config set registry https://registry.npmmirror.com

步骤 2：修改后端接口地址（如需要）

前端的 API 地址配置文件通常在 src 目录下的配置中。Snowy 前端默认请求后端 localhost:82，如果后端端口一致则无需修改。

步骤 3：启动前端开发服务器

# 开发模式启动（Vite 热更新）
pnpm dev
# 或
npm run dev

启动成功后访问 http://localhost:81 即可看到登录页面。

默认管理员账号：admin / 123456

运行效果

---

常见问题汇总（FAQ）

Q1：Maven 刷新一直转圈怎么办？

检查以下几点：

1. 镜像地址是否能访问（浏览器打开试试）
2. 是否有代理/VPN 干扰（尝试关闭）
3. 查看 IDEA 底部 Build Output 日志中的具体错误

Q2：Java 版本兼容性问题？

项目 pom.xml 要求 Java 17，但 JDK 21 完全向下兼容 JDK 17，无需降级。只需确保 IDEA 的 Project SDK 设置为 JDK 21 即可。

Q3：端口 82 被占用？

在 application.properties 中修改 server.port 为其他端口（如 8082）。同时需同步修改前端配置中的后端地址。

Q4：如何查看所有依赖是否下载完整？

mvn dependency:tree -f /Users/renxing/code/java/snowy/pom.xml | grep MISSING

没有输出说明所有依赖齐全。

Q5：Redis 必须装吗？

必须的。Snowy 大量使用了 Redis（Sa-Token 会话缓存、验证码、分布式锁等），不启动 Redis 无法正常运行。

---

总结

本次搭建过程中遇到的问题主要集中在 Maven 依赖下载环节，核心原因是：

问题	根因	解决方案
SSL 握手失败	国内网络无法稳定访问 HTTPS 外网仓库	配置国内镜像 + JVM SSL 参数
失败缓存不重试	Maven 缓存 .lastUpdated	find 删除所有 lastUpdated 文件
内部模块找不到	dependency:resolve 不编译本地模块	用 clean install 替代
IDEA 参数位置放错	Importer vs Runner	参数加在 Importing 中

只要迈过 Maven 这个坎，后面的数据库初始化 → Redis 启动 → 项目启动都是非常顺畅的。

Snowy 作为一款成熟的国产开源框架，文档相对完善，社区活跃（33K+ Star），非常适合作为企业级后台管理系统的脚手架。如果你也在考虑选型，不妨一试！

---

参考链接：

• Snowy 官方仓库：https://gitee.com/xiaonuobase/snowy
• Snowy 官方文档：https://xiaonuo.vip/doc
• Snowy 在线演示：https://snowy.xiaonuo.vip
• Spring Boot 官方文档：https://spring.io/projects/spring-boot

---

本文基于 Snowy v3.6.2 版本编写，环境为 macOS + JDK 21 + MySQL 8.0 + Redis 8.2。

一点吐槽

本文踩坑经历和部分解决方案由WorkBuddy输出，再次表示感谢。但就是沟通历史中我上传的截图全都无法查看原图大图了，很悲伤。这是我第一次使用WorkBuddy AI（在同事的推荐之下）。就解决了这一个问题，然后就“模型资源超出限量”😂

算了，我以后还是老老实实地用DeepSeek和豆包吧~