命令行与文本处理 / 系统课时
分离配置与运行环境
分离配置与运行环境
把路径、端点和功能开关写死在脚本中,会导致开发、测试和生产环境只能靠改代码切换。本课将建立配置加载与覆盖规则,让脚本从 JSON 文件读取非敏感配置,从环境变量读取部署差异和凭据,并在启动时完成校验。
学习目标
- 区分可提交配置、环境差异与敏感凭据
- 实现“配置文件加环境变量”的参数注入
- 建立明确的覆盖优先级和启动校验
划分配置边界
配置文件适合保存端点默认值、相对路径、超时和功能开关,并可随代码进行版本管理。环境变量适合注入容器、计划任务或 CI/CD 环境中的差异值。令牌和密码不应写入配置文件,配置中只保存其环境变量名称。
推荐采用以下优先级:命令行参数高于环境变量,环境变量高于配置文件,配置文件高于代码默认值。优先级必须固定并写入文档,否则同一个参数在不同机器上可能得到不同解释。

准备环境配置文件
以下 settings.json 只保存可公开的运行参数。tokenEnvironmentVariable 是凭据引用,不是令牌本身。
{
"endpoint": "https://api.example.internal",
"outputPath": "./out",
"timeoutSeconds": 20,
"features": {
"enableArchive": false
},
"credentials": {
"tokenEnvironmentVariable": "APP_API_TOKEN"
}
}该文件生效后,脚本仍允许使用 APP_ENDPOINT、APP_OUTPUT_PATH 和 APP_ENABLE_ARCHIVE 覆盖对应值。真实令牌由 APP_API_TOKEN 提供,不进入仓库。
实现加载、覆盖与校验
将下面脚本保存为 run.ps1,并与 settings.json 放在同一目录。脚本先读取 JSON,再应用环境变量覆盖,最后校验端点、超时和凭据是否有效。
[CmdletBinding()]
param(
[string]$ConfigPath = (Join-Path $PSScriptRoot 'settings.json')
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
function ConvertTo-Boolean {
param(
[Parameter(Mandatory)]
[string]$Value,
[Parameter(Mandatory)]
[string]$Name
)
$parsed = $false
if (-not [bool]::TryParse($Value, [ref]$parsed)) {
throw "环境变量 $Name 必须是 true 或 false。"
}
return $parsed
}
if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) {
throw "找不到配置文件:$ConfigPath"
}
$configDirectory = Split-Path -Parent (Resolve-Path -LiteralPath $ConfigPath)
$config = Get-Content -LiteralPath $ConfigPath -Raw |
ConvertFrom-Json
# 环境变量只覆盖已定义的部署差异,不改变配置结构。
$endpoint = if ($env:APP_ENDPOINT) {
$env:APP_ENDPOINT
}
else {
$config.endpoint
}
$outputPathValue = if ($env:APP_OUTPUT_PATH) {
$env:APP_OUTPUT_PATH
}
else {
$config.outputPath
}
$enableArchive = if ($env:APP_ENABLE_ARCHIVE) {
ConvertTo-Boolean -Value $env:APP_ENABLE_ARCHIVE `
-Name 'APP_ENABLE_ARCHIVE'
}
else {
[bool]$config.features.enableArchive
}
$tokenVariableName = [string]$config.credentials.tokenEnvironmentVariable
$token = [Environment]::GetEnvironmentVariable($tokenVariableName)
$endpointUri = $null
if (-not [Uri]::TryCreate($endpoint, [UriKind]::Absolute, [ref]$endpointUri) -or
$endpointUri.Scheme -notin @('http', 'https')) {
throw 'endpoint 必须是绝对 HTTP 或 HTTPS 地址。'
}
if ([int]$config.timeoutSeconds -le 0) {
throw 'timeoutSeconds 必须大于 0。'
}
if ([string]::IsNullOrWhiteSpace($token)) {
throw "未设置凭据环境变量:$tokenVariableName"
}
$outputPath = if ([IO.Path]::IsPathRooted($outputPathValue)) {
[IO.Path]::GetFullPath($outputPathValue)
}
else {
[IO.Path]::GetFullPath(
(Join-Path $configDirectory $outputPathValue)
)
}
# 只输出脱敏后的统一配置对象,业务代码无需知道参数来源。
[pscustomobject]@{
Endpoint = $endpointUri.AbsoluteUri
OutputPath = $outputPath
TimeoutSeconds = [int]$config.timeoutSeconds
EnableArchive = $enableArchive
TokenLoaded = $true
}预期结果。配置有效时,脚本输出一个脱敏后的统一配置对象;配置文件缺失、端点非法、超时非正数或凭据未注入时,脚本会立即抛出终止错误。脚本不会输出令牌值,业务函数也无需知道参数来自文件还是环境变量。
运行并验证覆盖规则
在 PowerShell 7 中执行以下命令。示例覆盖端点和功能开关,同时注入测试令牌。
$env:APP_ENDPOINT = 'https://test-api.example.internal'
$env:APP_ENABLE_ARCHIVE = 'true'
$env:APP_API_TOKEN = 'test-token-value'
./run.ps1 | Format-List预期输出
Endpoint : https://test-api.example.internal/
OutputPath : <PATH>
TimeoutSeconds : 20
EnableArchive : True
TokenLoaded : True<PATH> 是根据 settings.json 所在目录解析得到的绝对路径,实际值会因保存位置不同而变化。输出中的端点和开关来自环境变量,超时和输出路径来自配置文件,说明覆盖顺序已经生效。
管理多环境与失败边界
可以为不同环境准备 settings.dev.json、settings.test.json 和 settings.prod.json,部署时只通过 -ConfigPath 选择文件,不修改脚本。环境文件应保持相同字段结构,避免业务代码出现环境分支。
启动阶段应采用“快速失败”:配置文件缺失、布尔值非法、端点格式错误或凭据未注入时立即终止。不要静默回退到危险默认值,也不要在错误消息中打印令牌、密码或完整连接字符串。