EncryptedCast 不是透明加密，仅在Eloquent模型读写时加解密，数据库存密文且不支持WHERE查询；适用于无需搜索的敏感字段，不可用于需可搜索加密的场景。
直接说结论：Eloquent 的 EncryptedCast 不是开箱即用的“透明加密”，它依赖 encrypter 服务且仅在模型属性读写时生效，数据库字段本身不加密、不索引、不支持 WHERE 查询 —— 想靠它实现「字段级加密 + 可搜索」会踩坑。
为什么 EncryptedCast 不能替代应用层加密逻辑
Laravel 自带的 EncryptedCast（位于 Illuminate\Database\Eloquent\Casts\Encrypted）本质是把值交给 encrypter 服务加解密，但它只在模型 $casts 中声明后才触发，且全程绕过数据库约束和索引机制：
- 加密后的值以 Base64 字符串存入数据库（如
eyJpdiI6Ij...），长度固定但不可读、不可比、不可索引 - WHERE 子句中直接写
where('ssn', '123-45-6789')查不到数据 —— 因为数据库里存的是密文，不是明文 - 如果模型没加载、或用了
DB::table()原生查询，加密逻辑完全不生效 - 密钥轮换困难：旧密文无法自动重加密，必须手动遍历解密再加密
如何正确声明和使用 EncryptedCast
它只适用于「敏感但无需查询」的字段，比如用户备注、内部日志、临时凭证等。正确用法需满足三个条件：
- 模型类必须启用
protected $casts = ['field_name' => 'encrypted'];（Laravel 9+ 支持字符串简写；旧版需Encrypted::class） - 对应字段数据库类型应为
TEXT或JSON（避免被截断；VARCHAR(255)容易溢出） - 确保
config/app.php中'cipher' => 'AES-256-CBC'与APP_KEY有效 —— 否则运行时报RuntimeException: The only supported ciphers are AES-128-CBC and AES-256-CBC
示例：
立即学习“PHP免费学习笔记（深入）”；
class User extends Model
{
protected $casts = [
'private_notes' => 'encrypted',
'api_token' => 'encrypted',
];
}
此时 $user->private_notes = "test"; 写入的是密文；取值时自动解密，对开发者“透明” —— 但仅限于 Eloquent 实例上下文。
遇到 DecryptException 怎么排查
常见报错：Symfony\Component\HttpFoundation\Exception\SuspiciousOperationException: The payload is invalid. 或更具体的 Illuminate\Contracts\Encryption\DecryptException。根本原因几乎都是密钥不一致：
- 部署时
.env中APP_KEY被覆盖或未同步（Docker 多实例、CI/CD 构建镜像时容易漏） - 本地开发用
php artisan key:generate重置了 key，但数据库里已有旧密文 - 跨环境迁移数据时，生产 key 未导出到测试库
临时调试可加日志验证：
// 在模型的 getAttribute 方法里临时加
if ($key === 'private_notes') {
\Log::info('Raw DB value:', ['raw' => $this->getOriginal($key)]);
}
看到原始密文后，可用 app('encrypter')->decrypt($raw) 手动测试是否可解 —— 若失败，说明 key 或 iv 不匹配。
真正需要可搜索加密字段？别用 EncryptedCast
如果业务要求「加密存储 + 支持模糊查/等值查」（如身份证号、手机号），EncryptedCast 无解。必须切换策略：
- 用
libsodium的crypto_secretbox做 deterministically encrypted（确定性加密），但需自行管理 nonce 和密钥派生 - 引入专用库如
spatie/laravel-db-encrypted-columns，它提供EncryptedColumntrait 并支持whereEncrypted查询语法 - 更彻底的方案：改用应用层加密 + 数据库字段分离，明文哈希存索引字段（如
ssn_hash），密文另存（如ssn_enc），查时先比哈希再取密文解密
记住：EncryptedCast 是“方便但脆弱”的封装，它的价值在于快速屏蔽低敏字段，而不是构建安全边界。密钥管理、查询需求、合规审计 —— 这些都得自己兜底。
