Config files or environment variables for multi-environment? After a wrong production DB, I switched.

For multi-environment configuration, the more hassle-free combination is: environment variables handle overrides for differing items, while config files hold only defaults. If you also extract sensitive information separately and inject it via the deployment platform or a secret management service, you can let local, test, and production each run their own values without changing code. By 2026, cloud-native environments generally come with such injection capabilities built in, and this combination has become the default choice in most teams. The judgment criterion is simple: Parameters that change across environments should not be hardcoded in source code.

Why multi-environment configuration often goes wrong during delivery

The pitfalls in multi-environment configuration are not about technical implementation, but about "who changed which value and when." Three common incidents occur in projects: the test environment connects to the production database, local configuration gets committed to the repository, and temporary online parameter changes are not synced to the config center. What these incidents share is inconsistent configuration sources, causing the same code to behave differently across machines.

A very common consequence of misconfiguration is not an error, but "looks normal but data is written to the wrong place." For example, when the test environment connects to the production database and deletes a batch of online data, such an incident is often not discovered until the next day. Therefore, configuration management is essentially risk control, not just a development efficiency issue. From experience, the troubleshooting time for such configuration incidents typically ranges from tens of minutes to half a day, and recovery time in production is even longer.

• Hardcoded backend API addresses during joint debugging require code changes and repackaging when switching environments.
• The same configuration yields inconsistent results across machines; after hours of troubleshooting, you find an environment variable is missing.
• Using production configuration for local debugging nearly corrupts real data.

What's the difference between config files, environment variables, and a config center?

Config files are a product of version control, suitable for storing default values that don't change with the environment; environment variables are runtime injections, suitable for differing items that are unique to each environment; a config center is suitable for dynamic refresh and centralized auditing, but requires an additional component. The three are not an either/or choice, but are combined based on the scenario. Following 2026 project delivery habits, teams typically combine all three.

Take modifying a configuration value as an example. The typical time cost is as follows:

• Config file: It goes with the code repository, allowing review and rollback; but there is a leak risk when it contains sensitive information. After modification, it must go through commit, review, build, and deployment, typically taking 20 minutes to 2 hours.
• Environment variable: Injected by the deployment platform, it is not written to disk or database; but it becomes hard to manage when there are many. After modification, restarting the service takes effect, typically taking 3 to 10 minutes.
• Config center: It can be dynamically modified and takes effect, suitable for medium-to-large teams; but the introduction and operation costs are higher. After modification, it takes effect in seconds to tens of seconds, but the config center itself needs to be highly available.

The judgment criterion is straightforward: if a value differs across production, test, and local environments, put it in an environment variable; if it's the same in all three and not sensitive, a config file suffices; if the number of configuration items is still within the typical range (10–30), environment variables are enough; when it exceeds 30 and dynamic adjustments are needed, adopt a config center. Note that this is an "experience range," and the exact number should be adjusted to your team size.

In a single project, the three complement each other: environment variables handle overrides, config files provide fallbacks, and a config center is used for scenarios requiring centralized management.

A practical three-layer configuration approach

Based on our team's delivery experience, it can be split into three layers by priority from high to low: environment variables > local config override files > default config files. This ensures deployment flexibility without sacrificing local debugging convenience. The override file can be understood as an extra config on the developer machine, such as application-local.yml, which only contains the items that need to be overridden for local debugging.

1. First, create a default config file and put common items that don't vary by environment into it.
2. Then define an environment difference checklist, listing each differing point and noting its source.
3. Finally, in the startup script or deployment platform, inject the differing items via environment variables, and disable direct modifications to the repository config.

Notes for each layer: the default config should ensure the system can start even without environment variables; the difference checklist should go through code review to prevent someone from changing it temporarily on the server without syncing; environment variable naming should use a consistent prefix, such as APP_. This division lets different roles manage their own parts: developers change default values, operations adjust environment variables, avoiding mutual overwrites.

A common failure is: in step one, the default config contains the test database address, so local environments without environment variables connect directly to the test database; in step two, nobody maintains the difference checklist, and new team members don't know where to add items; in step three, the deployment script misses a variable, the program uses the default value, and functionality degrades. To solve this, add a validation step in the CI pipeline to check that all required environment variables have values. From experience, projects with 10 to 30 configuration items in total can already use the three-layer approach; beyond this range, consider introducing a config center.

On-site delivery: rework caused by configuration chaos

I worked on an internal management system project with a tight budget and a two-week schedule. The client required separate deployments for local, test, and production environments. We initially put the database address in config files. During joint debugging, the test environment accidentally connected to the production database. After discovering it, we had to work overnight to modify code and add environment variables, causing two days of rework. The typical schedule for such projects is 1 to 3 months; two weeks is quite tight, so the rework cost was very high.

Afterward, we changed to "config files only hold default items, environment variables handle all injection." When facing a new environment, we didn't need to modify code; we just copied a set of environment variables on the deployment platform. As a result, joint debugging progressed again, and the client didn't raise configuration issues during acceptance. This case shows that configuration decisions should be made early in development, not remedied at deployment time. If we had followed the three-layer approach from the start, this rework could have been avoided.

Common pitfalls and acceptance criteria

Even knowing the principle, you can still step on traps in details. The following points appear repeatedly in projects:

• Writing database passwords into config files and committing them to a Git repository—even if the repository is private, environment variables are recommended.
• When environment variables are not set locally, the program crashes directly; you should use default config as a fallback.
• Environment variables are case-sensitive on different operating systems; it's recommended to use uppercase consistently.
• When deploying with Docker, forgetting to pass environment variables results in the image containing the old configuration.
• When the number of configuration items is large (e.g., more than 30), it's recommended to introduce a config center for unified management instead of relying solely on environment variables.

What counts as qualified? Following delivery acceptance habits, you can do a "configuration checklist review": run a full deployment in the test environment, check each environment variable value one by one against the checklist, and confirm that no item is hardcoded in code. At the same time, if the local environment can't connect to the test database and the default config file allows it to run, that's basically qualified. More rigorous teams also check in CI scripts whether sensitive information has been committed to the repository.

Applicable scenarios and boundaries

This "environment variables + default config" approach works well for projects with clearly multiple deployment environments, such as dev, test, and production, or when delivering to customers who each deploy independently. It also fits scenarios with many microservices that need a unified configuration entry point.

But the boundaries should be clear: if a project has only a single deployment environment, or all parameters are public, then a single config file is enough—don't force environment variables. Additionally, if there are particularly many config items and they change frequently, a config center (e.g., Apollo or Nacos) is recommended, rather than manually writing everything with environment variables. As a common practice in 2026, config centers are more for medium-to-large teams; small projects may only add learning costs.

Another boundary: if no one on the team is familiar with maintaining environment variables, you can start with config files, but be intentional about extracting sensitive information. Don't introduce a config center just to be "advanced"; wait until the number of config items truly becomes unmanageable.

Frequently asked questions

Where should environment variables be set so they aren't overwritten?

Generally, set them in the deployment platform's configuration items or startup scripts, with higher priority than in-code configuration. The prerequisite is that the code leaves default values as fallbacks, so local debugging won't crash even when environment variables are missing.

When mixing config files and environment variables, which has higher priority?

Environment variables take priority. This allows the deployment platform to override local defaults and avoids the production environment accidentally reading test configuration. If a project has both config files and environment variables, environment variables prevail.

Should the database connection address go in a config file or environment variable?

It's recommended to use environment variables. Database addresses almost always differ across environments and carry sensitive information; using environment variables prevents accidental commits to the repository. If you're using a config center, you can also put the database connection string there for unified management.

What if there are too many config items and environment variables become messy?

When the number of config items clearly exceeds the typical range (e.g., more than 30) or dynamic refresh is needed, introduce a config center for unified management, while retaining a few environment variables for basic parameters. In the early stages, you can start with the three-layer approach and switch to a config center when it truly gets messy.

In practice, first spend half a day to a full day reviewing the configuration checklist of the existing project, marking the differing items, then decide which ones go to environment variables and which stay in config files. For new projects just starting out, it's recommended to begin with the three-layer configuration approach. If the project scale is small, you don't need to chase a config center—avoid overengineering. Based on team delivery experience, the earlier you decide on a configuration strategy, the less friction you'll face in later joint debugging and go-live.