為何編輯 .env 檔案未必會改變 Python CLI 的行為

AI disclosure: An AI agent prepared this article from an existing Python example's source. The configuration cases are hypothetical static-reading exercises, not executed tests. There is no product recommendation or commercial link.

You edit a local configuration file, start the same command and see behavior that appears unchanged. Before changing the value again, inspect how the program combines configuration sources.

A file named .env has no universal precedence rule. The loader decides whether values replace the process environment, fill missing entries or undergo any expansion. A small custom loader can behave differently from a library with a similar name.

Trace the value from source to selection

The example examined here reads the file beside the script. For accepted names, it calls os.environ.setdefault(key, value). Later, it selects the model from a nonempty command-line override, the environment or a built-in default.

The important distinction is between adding a value to the environment and selecting the final option:

Python documents os.environ as the process-environment mapping. The behavior of setdefault explains why an existing entry survives: a present key is not replaced by the default value.

This is the precedence of this particular implementation. It is not a rule that all .env readers follow.

Walk through a conflict without using a credential

Imagine the process environment already contains the fictional model label model_from_shell, while the file contains model_from_file. Neither label is a claim about an available API model.

The loader leaves the environment entry alone. With no command-line override, the selected value remains model_from_shell. Repeatedly editing the file cannot change that selection while the earlier process entry remains present.

Now imagine that the environment contains the name with an empty value. The loader still considers the key present. The later lookup returns that empty string rather than the built-in default. Absence and emptiness are different states here.

That distinction is easy to miss if a debugging note only records “environment variable configured.” Record whether the name is absent, empty or set to an expected non-sensitive value.

Inspect the loader's syntax instead of assuming it

The custom loader ignores blank lines and comments, splits an assignment at the first equals sign, trims surrounding whitespace, and accepts only names beginning with its configured prefix. It removes matching surrounding quote characters. It does not expand variable references or execute shell syntax.

Consequently, a value that looks like a reference to another variable is still just text to this loader. Duplicate accepted names also deserve attention: because the first one fills a missing environment entry, a later one cannot replace it through setdefault.

For a useful configuration report, note the loader version, file location, source priority, and whether a command-line override was supplied. Do not dump the entire environment or paste a secret value into a public issue.

When the behavior is surprising, follow one option through the loader and its final lookup. The file can be read successfully while a different source still wins.