文章目录

Nacos 配置中心

参考官方文档：Spring Cloud Alibaba 2025.x 进阶指南

一、配置优先级

Spring Boot 加载配置的优先级（从高到低）：

在这里插入图片描述

1.1 建议

  • 敏感信息（密码、密钥）放 Nacos，不放本地 yml
  • 固定结构（MyBatis 路径等）可留本地
  • 环境差异（端口、数据库地址）放 Nacos + Namespace 隔离

二、依赖版本

组件2025.x（当前项目）2023.0.x（上一主流版）
Spring Boot4.1.03.2.x
Spring Cloud2025.1.22023.0.x
Spring Cloud Alibaba2025.1.0.02023.0.x
Nacos Config 依赖spring-cloud-starter-alibaba-nacos-config相同

三、核心概念：Data ID、Group、Namespace

在这里插入图片描述

Nacos 通过三个维度组织配置：

Namespace（命名空间）
    └── Group（分组）
            └── Data ID（配置文件）

3.1 Namespace（命名空间）

实现环境隔离（开发 / 测试 / 生产）或多租户隔离。不同 Namespace 的配置完全隔离，互不可见。

spring:
  cloud:
    nacos:
      config:
        namespace: 14976256-c71e-4138-b0b1-6aa2644ef289   # 填 Namespace ID

不配置时，默认使用 Nacos 的 public 命名空间。

3.2 Group（分组）

在 Namespace 内部，对配置做分类管理（按应用、业务模块等）。默认分组为 DEFAULT_GROUP。

spring:
  cloud:
    nacos:
      config:
        group: DEFAULT_GROUP

spring.config.import 中也可单独指定：

spring:
  config:
    import:
      - nacos:product-service-dev-db.properties?group=DB_GROUP&refreshEnabled=true

3.3 Data ID（数据标识）

具体配置文件的唯一标识，通常遵循 {应用名}-{环境}.{后缀} 命名规范。

在 Nacos 控制台创建配置时填写：

字段示例
Data IDproduct-service-dev.properties
GroupDEFAULT_GROUP
格式Properties / YAML / JSON 等

应用侧通过 spring.config.import 引用：

spring:
  config:
    import:
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true

四、2025.x 完整接入步骤

4.1 引入依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

4.2 Nacos 控制台创建配置

字段值
Data IDproduct-service-dev.properties
GroupDEFAULT_GROUP
Namespacedev（14976256-c71e-4138-b0b1-6aa2644ef289）
格式Properties

内容：

server.port=9898

4.3 application.yml

spring:
  application:
    name: product-service
  profiles:
    active: dev
  config:
    import:
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: 14976256-c71e-4138-b0b1-6aa2644ef289
        group: DEFAULT_GROUP

4.4 验证

启动 product-service，日志中端口应为 9898（来自 Nacos，而非本地 yml）。

在 Nacos 控制台修改 server.port=9899 并发布，应用会自动刷新（refreshEnabled=true）。

五、近两个版本的依赖与导入差异

5.1 依赖差异

2023.0.x 早期（≤ 2023.0.1.2，bootstrap 模式）

需要两个依赖：

<!-- 1. Nacos 配置中心 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

<!-- 2. Bootstrap 引导启动（使用 bootstrap.yml 时必须引入） -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

Spring Boot 2.4 之后默认关闭了 bootstrap 机制，要用 bootstrap.yml 加载 Nacos 配置，必须额外引入 spring-cloud-starter-bootstrap，否则 bootstrap.yml 不会生效。

2025.1.x 起

只需一个依赖，且禁止使用 bootstrap：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

2025.1.x 已明确移除 bootstrap 支持，引入 spring-cloud-starter-bootstrap 会导致配置刷新失效。

依赖对比汇总
版本依赖数量依赖项
2023.0.x 早期（bootstrap 模式）2 个nacos-config + spring-cloud-starter-bootstrap
2025.x1 个nacos-config（禁止 bootstrap）

5.2 配置导入方式（核心差异）

对比项2023.0.x 早期2025.x
依赖数量2 个（nacos-config + bootstrap）1 个
推荐方式bootstrap.yml + shared-configsspring.config.import
Bootstrap必须引入 bootstrap 依赖已移除
shared-configs可用(对同一 Namespace 下的所有应用生效)已移除
extension-configs可用(对单一服务生效)已移除
默认加载 {app name}.{ext}自动拼接需手动 import
缺少 nacos 导入项不强制报错启动时报错
2023.0.x 早期写法（bootstrap 模式，需两个依赖）

bootstrap.yml：

spring:
  application:
    name: product-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
        namespace: dev-namespace-id
        shared-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true
        extension-configs:
          - data-id: product-service-ext.yaml
            group: DEFAULT_GROUP
            refresh: true

旧版会自动加载 {spring.application.name}.{file-extension}，配置写在 bootstrap.yml，需配合 spring-cloud-starter-bootstrap 依赖。

2025.x 写法（新，当前项目使用）

application.yml：

spring:
  application:
    name: product-service
  config:
    import:
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true
      - optional:nacos:common.properties?group=DEFAULT_GROUP&refreshEnabled=true
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: 14976256-c71e-4138-b0b1-6aa2644ef289
        group: DEFAULT_GROUP

2025.x 必须在 spring.config.import 中显式声明每一条 Nacos 配置，不再自动拼接 Data ID。

启动检测差异

2025.x 引入 spring-cloud-starter-alibaba-nacos-config 后，若 import 中没有 nacos: 条目，启动报错：

The spring.config.import property is missing a nacos: entry

解决方式（三选一）：

# 1. 添加 nacos 导入（推荐）
spring.config.import:
  - nacos:your-config.properties

# 2. 可选导入，允许不存在
spring.config.import:
  - optional:nacos:your-config.properties

# 3. 关闭检测（不推荐）
spring.cloud.nacos.config.import-check.enabled: false

六、spring.config.import 写法大全

6.1 基本格式

[optional:]nacos:{DataId}?group=xxx&refreshEnabled=true
部分说明
nacos:固定前缀
optional:配置不存在时不报错，应用正常启动
{DataId}Nacos 控制台的 Data ID，如 dev-111、product-service-dev.properties
group分组，默认 DEFAULT_GROUP
refreshEnabled是否动态刷新，默认 true

6.2 常见示例

spring:
  config:
    import:
      # 必导：不存在则启动失败
      - nacos:dev-111?group=DEFAULT_GROUP&refreshEnabled=true

      # 可选：不存在则跳过
      - optional:nacos:common.properties?group=DEFAULT_GROUP&refreshEnabled=true

      # 指定非默认 Group
      - nacos:product-service-dev-db.properties?group=DB_GROUP&refreshEnabled=true

      # 关闭动态刷新
      - nacos:static-config.properties?group=DEFAULT_GROUP&refreshEnabled=false

      # 同时导入多个
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true
      - nacos:common.properties?group=DEFAULT_GROUP&refreshEnabled=true

6.3 完整 application.yml 示例

spring:
  application:
    name: product-service
  config:
    import:
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: 14976256-c71e-4138-b0b1-6aa2644ef289
        group: DEFAULT_GROUP
        file-extension: properties

Nacos 控制台对应配置内容（Properties 格式）：

server.port=9898
datasource.url=jdbc:mysql://localhost:3306/cloud_product
datasource.username=root
datasource.password=247711

七、命名规范

7.1 Data ID 推荐格式

<应用名>-<环境>-<配置类型>.<后缀>
示例说明
product-service-dev.properties商品服务 - 开发环境 - 主配置
product-service-prod.properties商品服务 - 生产环境 - 主配置
order-service-dev-db.properties订单服务 - 开发环境 - 数据库配置
common-dev.properties公共配置 - 开发环境

八、环境隔离

为不同环境创建独立 Namespace，dev / prod 配置完全隔离。

application-dev.yml:

spring:
  cloud:
    nacos:
      config:
        namespace: 14976256-c71e-4138-b0b1-6aa2644ef289
  config:
    import:
      - nacos:product-service-dev.properties?group=DEFAULT_GROUP&refreshEnabled=true

dev 环境的应用只能读到 dev Namespace 下的配置，与 prod 完全隔离。

九、版本管理

Nacos 控制台提供历史版本功能，每次修改配置都会保留历史记录。

9.1 使用方式

  1. 进入 Nacos 控制台 → 配置管理 → 配置列表
  2. 点击目标配置的「历史版本」
  3. 选择历史版本 → 回滚

9.2 最佳实践

  • 修改生产配置前，先在 dev Namespace 验证
  • 重要变更在控制台备注修改原因
  • 出问题后通过历史版本快速回滚，无需重启应用（配合 refreshEnabled=true 可自动生效）

十、总结

主题要点
三维模型Namespace 隔离环境 → Group 分类 → Data ID 标识文件
2023 vs 2025早期 2023 需 2 个依赖（nacos-config + bootstrap）；2023.0.1.3+ 和 2025 只需 1 个；导入方式统一为 spring.config.import
命名规范Data ID：<应用名>-<环境>-<类型>.properties；配置项：<模块>.<功能>.<属性>
环境隔离不同 Namespace，填 Namespace ID
版本管理控制台历史版本，一键回滚
高可用Nacos 集群 + Nginx，server-addr 逗号分隔
优先级JVM > 环境变量 > Nacos > 本地 yml
# java # 数据库 # redis
Logo
AI硬件创业社区

智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。

更多推荐

cover

【STM32F4】基于RTOS的智能门禁系统实战：人脸识别+RFID+OTA 升级

avatar AI硬件创业社区
cover

基于多模态生物识别的智能门锁系统设计|毕设答辩|单片机项目|毕业设计

avatar AI硬件创业社区
cover

基于多态传感器数据融合的智慧仓储火灾预警系统 |毕设答辩|单片机项目|毕业设计

avatar AI硬件创业社区