Master Multi-Environment Config with Spring Boot 3.x and Nacos

Background and Goal

The article explains how to integrate Nacos as a service discovery and configuration center into a Spring Boot 3.x project, focusing on clean separation of development, testing, and production environments and enabling dynamic configuration refresh.

Install Nacos Server

Download the Nacos binary and start it in standalone mode using -m standalone.

Access the console at http://localhost:8848/nacos.

Log in with the default credentials nacos / nacos.

Configure Spring Boot 3.x Project

Create a new project with Spring Initializr, selecting Spring Boot 3.x.

Add the following Maven properties and dependencies:

<spring-cloud.version>2022.0.4</spring-cloud.version>
<spring-cloud-alibaba.version>2022.0.0.0</spring-cloud-alibaba.version>

Include the Nacos starter libraries:

spring-cloud-starter-alibaba-nacos-discovery
spring-cloud-starter-alibaba-nacos-config

bootstrap.yml Core Settings

spring:
  application:
    name: demo-app
  profiles:
    active: dev
  cloud:
    nacos:
      config:
        server-addr: localhost:8848
        file-extension: yaml
        namespace: <dev-namespace-id>
        group: DEFAULT_GROUP
      discovery:
        server-addr: localhost:8848
        namespace: <dev-namespace-id>
        group: DEFAULT_GROUP

Multi‑Environment Config in Nacos

Create separate namespaces for dev, test, and prod.

Follow the Data ID naming rule {appname}-{profile}.yaml, e.g., demo-app-dev.yaml, demo-app-test.yaml, demo-app-prod.yaml.

Example content for demo-app-dev.yaml:

server:
  port: 8081
custom:
  config: Hello from Nacos Dev!

Code Example and Test

Application entry point:

@SpringBootApplication
@EnableDiscoveryClient
public class YourApplication { ... }

Controller that reads the dynamic configuration:

@RestController
@RefreshScope
public class TestController {
    @Value("${custom.config:Local default}")
    private String customConfig;

    @GetMapping("/config")
    public String getConfig() {
        return customConfig;
    }
}

Run and Verify

Start the Spring Boot application; logs should show that Nacos configuration has been loaded.

Access /config to see the value from the current environment.

Switch environment with -Dspring.profiles.active=test and observe automatic loading of demo-app-test.yaml.

Modify the configuration in Nacos console; the /config endpoint reflects the change without restarting thanks to @RefreshScope.

Best Practices

Environment isolation: Use separate namespaces for each environment.

Configuration naming: Follow appname-profile.ext pattern.

Configuration grouping: Use groups to separate projects or purposes.

Dynamic refresh: Annotate beans with @RefreshScope to enable hot updates.

By following these steps, your Spring Boot 3.x application can seamlessly integrate Nacos, support multi‑environment configurations, and enjoy graceful dynamic refresh capabilities.