Guava Docs

Appearance

构建与部署常见问题 ​

这里汇总后端构建和部署过程中最常碰到的问题，直接找相关场景。

构建相关 ​

Q: 怎么打包生产环境？ ​

  1. 打开 IDEA 右侧 Gradle 工具栏
  2. 展开对应模块 → Tasks → build
  3. 双击 bootJar 打包可执行 JAR（跳过测试）
  4. 双击 build 执行完整构建（含测试）

构建产物在 build/libs/ 目录下。

Q: 构建失败，报 Could not resolve 或依赖下载失败？ ​

原因：可能是 Gradle 缓存损坏、网络问题或依赖配置不正确。

解决：

  1. 刷新依赖：点击 IDEA 右侧 Gradle 工具栏的 刷新按钮（Reload All Gradle Projects）
  2. 清理缓存：在 IDEA 中打开 File → Invalidate Caches → Invalidate and Restart，勾选 "Clear file system cache and Local History"
  3. 检查网络：确保能访问 Maven 中央仓库，如网络受限可换一个网络环境重试
  4. 检查 JDK 版本：确认 IDEA 中 Gradle JVM 设置为 JDK 25（File → Settings → Build、Execution、Deployment → Build Tools → Gradle）

Q: 构建成功但启动报错 ClassNotFoundException 或 NoClassDefFoundError？ ​

原因：构建缓存不一致或依赖未正确打包。

解决：

  1. 清理构建产物：在 IDEA 的 Gradle 面板中执行 clean 任务（或使用菜单 Build → Clean Project）
  2. 重新构建：执行 Build → Rebuild Project
  3. 刷新依赖：点击右侧 Gradle 工具栏的 刷新按钮

部署相关 ​

Q: 应用启动报 IllegalAccessError？ ​

JDK 25 默认限制原生 API 访问，需要在启动配置中添加 JVM 参数：

  1. 打开 Run → Edit Configurations...
  2. 在 VM options 中添加：
--enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow

TIP

项目已通过 build.gradle.kts 自动注入上述参数到 IDEA Run Configuration，通常无需手动配置。

Q: 怎么回滚到上一个版本？ ​

通过 OAK 平台进行版本回滚：

  1. 进入项目管理页面
  2. 选择构建的历史版本
  3. 选择要回滚的版本
  4. 点击 "回滚"

WARNING

  • 回滚前确认目标版本稳定
  • 数据库变更需单独处理
  • 回滚后验证服务状态

生产环境相关 ​

Q: 生产环境配置不生效？ ​

原因：Nacos 配置中心的配置未正确加载或未推送到目标环境。

解决：

  1. 登录 Nacos 控制台，确认对应环境（namespace）下存在对应 dataId 的配置
  2. 确认 application.yml / bootstrap.yml 中的 spring.config.import 配置正确
  3. 确认部署环境的 namespace 与 Nacos 控制台一致
  4. 在 OAK 平台重新触发部署，确保最新配置被加载
  5. 启动日志中搜索 Loading nacos data 确认配置已加载

Q: Nacos 服务未注册到生产环境？ ​

确认 application-prod.yml 中的 Nacos 配置：

yaml
spring:
  cloud:
    nacos:
      discovery:
        namespace: <生产环境-namespace>
        group: <生产环境-group>