何昌全博客
WordPress 7.2 的 Secrets API 为 API 密钥、OAuth 客户端秘密等凭据提供统一的加密存储与读取接口，并保留前一个版本，方便凭据轮换。默认实现使用 libsodium 的 XChaCha20-Poly1305 加密记录，密文存放在 options 表中。
现有网站必须先准备 WP_SECRETS_KEY
官方开发说明明确指出，现有网站需要在 wp-config.php 中加入独立的 WP_SECRETS_KEY。新安装站点由安装器生成；现有站点可从“工具—站点健康”获得建议的配置行。
这个密钥不能留空、不能使用示例占位符，也不能直接复制现有认证 key 或 salt。缺少有效密钥时，Secrets API 不会存入任何内容，读取已存秘密也会返回错误。
不要把它当作普通 salt 随意更换。一旦站点已保存秘密，移除或更改密钥会让这些记录无法读取，直到旧值恢复或按官方轮换步骤迁移。
Secrets API 解决什么问题？
插件过去常把 API 密钥明文放在选项表或自建配置中。新 API 提供 wp_set_secret()、wp_get_secret()、删除、列出元数据和版本轮换等统一能力。主机也可以通过 wp-content/secrets.php drop-in 把 keyring、存储或整个提供器接到 KMS、HSM 或外部秘密管理服务。
这不等于升级后所有旧凭据会自动迁移。官方的 wp_import_option_as_secret() 会把现有 option 复制为 secret，但不会自动删除旧 option，并会标记凭据需要轮换。插件作者必须设计兼容读取、清理和回滚流程。
插件开发者的迁移顺序
- 先用
wp_is_secrets_api_available()确认 API 和密钥可用； - 使用
plugin-slug/secret-name形式命名，避免与其他插件冲突； - 区分“从未保存”的
null与“暂时无法读取”的WP_Error，不要在错误时覆盖仍有效的凭据； - 导入旧 option 后安排凭据轮换，再删除旧明文记录；
- 完成轮换后再退役 previous 版本，并验证回滚方案。
它不是插件之间的访问隔离
命名前缀只能防止误覆盖，不是权限控制。官方说明指出，运行在站点内的其他代码仍可能读取秘密；相关函数也不会自行检查用户 capability，因为它们需要在 Cron 与 REST 场景中工作。凡是让用户输入或管理秘密的界面，插件仍必须自己执行权限和 nonce 校验。
普通站长要检查什么？
如果网站只使用现成插件，不要自行删除旧密钥，先等待插件明确支持。WordPress 7.2 正式版计划于 2026 年 12 月 8 日发布。升级前可参考WordPress 7.2 测试站兼容性检查，但真实凭据应只放在受控的 staging 环境。
站点健康的“安全”部分会检查密钥来源、无法解密的秘密和待轮换凭据。出现“critical”时，不要立即生成新密钥覆盖旧值，应先保留配置与备份，按官方迁移步骤恢复或轮换。
测试时覆盖这些失败场景
- 密钥缺失、错误或外部提供器暂时不可用；
- 凭据从未保存与已保存但无法读取的不同处理；
- 轮换期间新旧凭据并存，服务端尚未全部更新；
- 日志、JSON 输出和调试工具不会暴露明文；
- 回退 WordPress 或插件版本后，旧连接方式仍可恢复。
Secrets API 改善的是凭据存储与轮换接口，不替代最小权限、插件审计和安全备份。正式迁移前，应在独立测试站完成连接、轮换与回滚验证。
