FrozenDictionary 是 .NET 8 引入的高性能只读字典，需目标框架 ≥.NET 8、引用 System.Collections.Frozen 命名空间，仅能通过 ToFrozenDictionary() 创建；支持 O(1) 索引查找与线程安全读取，但所有修改操作抛 NotSupportedException，且不支持 IDictionary.Contains(object) 等非泛型方法。
FrozenDictionary 是 .NET 8 中正式引入的高性能只读字典类型，位于 System.Collections.Frozen 命名空间，不是第三方封装，也不是误传的 ImmutableDictionary.ToImmutable()。它专为构建后永不修改、内存布局固化、零分配查找设计，比 ImmutableDictionary 查找快约 30–50%，GC 压力几乎为零。
如何正确引用和创建 FrozenDictionary
必须确保项目目标框架为 .NET 8 或更高（如 .NET 9），且已安装 System.Collections.Frozen 包（.NET 8 SDK 默认包含，但旧项目可能需显式添加）：
- 若使用
dotnet new创建的 .NET 8+ 项目，无需额外 NuGet 引用；否则在.csproj中确认存在：<PackageReference Include="System.Collections.Frozen" Version="8.0.0" />
- 命名空间必须显式引入：
using System.Collections.Frozen; - 不能直接
new FrozenDictionary<string, int>()—— 它没有公共构造函数，只能通过静态工厂方法创建 - 推荐方式是调用扩展方法
ToFrozenDictionary()，它接受任意IEnumerable<KeyValuePair<TKey, TValue>>
示例：
var dict = new Dictionary<string, int>
{
["apple"] = 1,
["banana"] = 2,
["cherry"] = 3
}.ToFrozenDictionary(); // ✅ 正确错误写法（编译失败）：
var bad = new FrozenDictionary<string, int>(); // ❌ no public ctor var alsoBad = dict.ToImmutable(); // ❌ 返回的是 ImmutableDictionary，不是 FrozenDictionary
FrozenDictionary 的查找行为与常见陷阱
它实现了 IDictionary<TKey, TValue>，但所有修改方法（Add、Remove、索引器赋值等）都会抛出 NotSupportedException，这是设计使然，不是 bug。
- 支持
dict["key"]直接索引访问，O(1) 平均时间复杂度（底层是优化哈希表，非二分） - 不支持
dict.ContainsKey("key")的IDictionary.Contains(object)重载 —— 因为该方法签名要求object，而FrozenDictionary显式实现该接口时会 throwNotSupportedException；应改用泛型安全的dict.TryGetValue("key", out var v) - 重复键处理：若源数据含重复
Key，ToFrozenDictionary()会保留序列中**最后一次出现的值**（不同于ToDictionary()抛异常） - 线程安全：读操作完全无锁，可被任意数量线程并发访问，无需额外同步
典型误用：
if (dict.Contains("apple")) { ... } // ❌ 编译通过但运行时 NotSupportedException
if (dict.ContainsKey("apple")) { ... } // ❌ 同上（IDictionary.ContainsKey 是 object 版本）
if (dict.TryGetValue("apple", out int val)) { ... } // ✅ 正确且高效性能关键：何时用 FrozenDictionary，何时换方案？
它不是万能替代品。适用场景非常明确：**一次性构建 + 高频只读查找 + 键集稳定**（如配置映射、HTTP 状态码描述、枚举名称缓存）。但要注意以下边界：
- 初始化开销略高：构建过程会做哈希表预分配 + 冲突探测优化，10 万条目耗时约 0.5–2ms，远高于
Dictionary构造，但只发生一次 - 内存占用比
Dictionary高约 10–15%，但比ImmutableDictionary低 30%+；底层无树节点/链表指针，纯数组 + 开放寻址 - 不支持自定义
IEqualityComparer<TKey>的运行时传入（ToFrozenDictionary(..., comparer)是允许的，但一旦冻结，comparer 即固化，无法后期替换） - 若键类型是自定义 class 且未重写
GetHashCode/Equals，或使用引用相等语义，务必传入对应IEqualityComparer，否则行为不可控 - 极小集合（ReadOnlySpan<KeyValuePair<TKey,TValue>> + 线性查找反而更快，
FrozenDictionary的哈希开销反而成负优化
一句话判断：如果你正在写 private static readonly 字典字段，且初始化后从不修改，FrozenDictionary 就是当前 .NET 8+ 下最优解。
兼容性与版本依赖必须看清
FrozenDictionary 不是 .NET Standard 兼容类型，它**仅存在于 .NET 8 及以上原生运行时**。这意味着：
- 目标框架为
net6.0或net7.0的项目无法使用 —— 即使手动引用System.Collections.Frozen8.x 包，运行时也会因类型缺失而报TypeLoadException -
net8.0-windows、net8.0-android等具体 TFM 均支持，无平台限制 - ASP.NET Core 8+、MAUI 8+、Blazor WebAssembly 8+ 均可直接用，但需确认发布时未降级目标框架
- 不要在共享库（如
netstandard2.0）中暴露FrozenDictionary类型，否则下游 .NET 6 项目引用即崩
检查是否真正在用原生实现：查看反编译后的程序集引用，确认 FrozenDictionary 类型来自 System.Collections.Frozen.dll（而非某第三方同名包），且其 AssemblyVersion 为 8.0.0.0 或更高。
最容易被忽略的一点：它的“冻结”是编译时契约 + 运行时防护的组合，不是魔法。只要构造完成，任何试图绕过只读性的反射或 unsafe 操作，都可能破坏内部哈希一致性 —— 所以别那么干。
