Spring 无法解析占位符 — 属性缺失

症状

本篇指南处理“Spring 无法解析占位符 — 属性缺失”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。

可观察到的症状包括：

• ApplicationContext 失败并提示 “Could not resolve placeholder ‘x’ in value "${x}"”
• 使用 dev profile 正常，prod 失败
• 属性存在于一个未被加载的文件中

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

java -jar app.jar 2>&1 | grep -A 2 "Could not resolve placeholder"

消息指出未解析的键，据此可确定应补充哪个属性。

步骤 2

java -jar app.jar --debug 2>&1 | grep -A 20 "PropertySourcesPlaceholder"

debug 日志会列出已加载的属性源与 profile，揭示该值的来源。

常见诱因（按出现频率排序）：

• 活动 profile 或环境中缺少该属性
• application-prod.properties 等 profile 文件不在类路径上
• 可选的 @Value 未提供默认值

根因

Spring 在创建 bean 时基于活动环境解析 ${…} 占位符。若没有任何属性源、profile 文件或环境变量提供该键，且未给默认值，解析即失败并中止上下文。

修复

把属性加入对应 profile 文件、以环境变量传入，或用 @Value(“${x:default}”) 提供默认值；并核实各环境的活动 profile。

注意：默认值可能掩盖缺失的生产配置；必需值应快速失败，仅为确有可选的项设默认。

@Service
public class MailService {
    // required -> fail fast if absent
    @Value("${mail.host}")
    private String host;

    // optional -> explicit default
    @Value("${mail.port:587}")
    private int port;
}

# application-prod.properties
mail.host=smtp.example.com

验证

用目标 profile 启动并确认上下文加载成功；记录解析后的值（脱敏）以证明属性源正确。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。