写 C# 的时候，params是一个绕不开的关键字，可它又常被当成“一个能让方法接收多个参数的语法糖”简单带过。真正到了写日志封装、拼接路径、设计公共 API 时，你会发现它背后还藏着数组创建、重载决策、性能分配这一连串没有写在入门文档里的细节。这篇教程不打算走“讲三条规则，跑个 Demo，结束”的路子，而是把这个关键字从语法到调用机制，从日常 API 到避坑经验，从旧版本到 C# 13 的新变化，全部摊开讲一遍。无论你是刚学 C# 的新手，还是写了好几年项目但没系统性琢磨过params的开发者，都能在这篇里找到值得收藏的东西。

1.1 没有 params 之前，代码还能怎么传参

先回到一个最简单的需求：写一个求和方法，让它能接收任意数量的整数。在没有params的年代，最朴素的做法是把参数声明成一个数组：

static int Sum(int[] numbers) { int total = 0; foreach (int n in numbers) { total += n; } return total; }

调用方必须先把参数包进数组再调用：

int a = Sum(new[] { 1, 2 }); int b = Sum(new[] { 1, 2, 3, 4, 5 }); int c = Sum(new int[0]); // 什么都不传也得建一个空数组

这段代码的问题不在方法内部，而在调用体验。业务代码里可能到处都是new[] { ... }，为了传三个数，得先写一段数组初始化，读起来又吵又影响主流程。更别扭的是“零个参数”这种边界情况，调用方得知道去创建一个空数组，否则编译器就会报错。params要解决的就是这个“调用侧被迫构造容器”的别扭感，它把数组的创建动作从调用方转移到了编译器身上。

1.2 params 的最小可运行示例：一个方法吃下所有调用姿势

把上面那个Sum改造成params版本，只差一个关键字：

static int Sum(params int[] numbers) { int total = 0; foreach (int n in numbers) { total += n; } return total; }

然后你会看到这些调用全部合法：

int r1 = Sum(1, 2); // 结果 3 int r2 = Sum(1, 2, 3, 4, 5); // 结果 15 int r3 = Sum(); // 结果 0，空数组 int r4 = Sum(new int[] { 7, 8 }); // 也可以显式传数组，结果 15

在方法内部，numbers就是一个普普通通的int[]，可以Length、可以foreach、可以下标访问。params没有改变参数的本质，它只是给了调用方一种“像写普通参数列表一样写可变参数”的权限。这也是为什么很多内置 API 都有params重载——比如string.Format,Console.WriteLine,Path.Combine，它们内部拿到本质还是一个数组。

如果你想传多个不同类型的值，可以把数组声明成object[]：

static void PrintAll(params object[] items) { foreach (object i in items) { Console.WriteLine(i); } } PrintAll(1, "hello", 3.14, true);

这段代码几乎是每个 C# 开发者见过但没细想过的最典型params object[]用法。后面我会专门讲它带来的装箱开销。先记住：params本身只要求参数是数组，并不限制数组元素类型。

1.3 三条硬性规则，以及为什么必须有这些规则

params的规则不多，但每一条都踩过编译错误的人肯定不在少数。

规则一：params 只能修饰一维数组。在 C# 13 之前这是硬性限制，多维数组如int[,]、嵌套数组如int[][]都不能用作params参数。原因是编译器做“可变参数展开”时，只能理解成“把一串实参塞进一个一维数组”，多维数组没法承载这种一一展开的语义。

规则二：params 必须是参数列表里的最后一个参数。如果写在前面，编译器无法判断后续的参数到底属于哪一个位置。比如：

// 编译错误：params 必须位于参数列表最后 static void Bad(params int[] nums, string name) { }

正确写法应该是static void Good(string name, params int[] nums)。这也是你在实际代码里最常见的形态：一个必填参数在前，若干个可选追加参数在后。

规则三：一个方法只能有一个 params 参数。原因同上，两个可变参数让参数边界无法切分。你想设计“接受任意个数字和任意个名字”的方法，正确做法是拆成两个方法或使用两个不同形态的参数，而不是两个params。

还有一条隐藏规则：params不能和ref、out、in组合使用。后面避坑章节再展开，这里只需要知道它们互斥即可。我把最常见的违规写法整理成表格，方便你对照：

规则的背后不是随意限制，而是为了让编译器能把“可变长度”和“固定位置”明确区分开。你只要记住：params本质是“数组参数 + 调用方免建数组的语法便利”，这些规则就都不难理解。

2.1 编译器在调用点做了什么：一次实打实的语法糖

当你在代码里写Sum(1, 2, 3)时，真实发生的调用并不是表面上“传了三个参数”。C# 编译器会把这次调用改写为大致这样：

int[] temp = new int[] { 1, 2, 3 }; Sum(temp);

也就是说，每次调用Sum(1, 2, 3)，都意味着创建了一个长度为 3 的int[]。这是params最核心的隐藏机制。很多人用params用得很顺手，却不知道每一次“顺手”背后都产生了一个数组对象，这对后续性能排查非常重要。

如果你是用数组形式调用Sum(existingArray)，编译器就不会重新复制数组，而是直接把existingArray的引用传进去。这里有个初学者常忽略的语义：params参数在方法内部是一个引用类型变量，它指向的数组和调用方的数组是同一个对象。下一节我会用一个例子说明它带来的实际影响。

2.2 空传与 null 传参：两者天差地别

Sum()和Sum(null)是两个完全不同的调用。Sum()会被编译器补成一个空数组new int[0]，所以方法内部numbers.Length得到的是 0，foreach不会执行任何循环体，不会出问题。

Sum(null)则是把字面量null直接作为数组引用传进方法，numbers变量本身是null。这时候如果方法内部直接执行：

foreach (int n in numbers) { }

运行时必定抛NullReferenceException，因为编译器要调用numbers.GetEnumerator()，而numbers是空引用。这是个很容易踩的坑：你以为传null会被“容忍”，实际上没有。写params方法时，第一行就做空参数保护是低成本高收益的做法：

static int Sum(params int[] numbers) { if (numbers == null) { return 0; } // 安全地使用 numbers }

在一些较新版本的 C# 可空引用类型上下文中，编译器还会给出警告，提示null可能被传给不可空的数组参数。语义上它仍然只是一个普通的 null 引用，不要指望编译器帮你“转成空数组”。

2.3 引用语义：方法里改数组，外面会跟着变

params参数既然是数组引用，那么通过数组形式调用时，方法内部修改数组元素就会作用于外部原始数组：

static void ChangeFirst(params int[] numbers) { numbers[0] = 999; } int[] arr = { 1, 2, 3 }; ChangeFirst(arr); Console.WriteLine(arr[0]); // 输出 999

这符合引用类型参数的全部预期。如果你写的方法需要避免副作用，应该在方法内部先复制数组：

static void SafeChange(int[] source) { int[] numbers = (int[])source.Clone(); numbers[0] = 999; }

少数场景下有人会利用这种引用性质做“修改传入数组内容”的批处理工具，但这会让调用方很意外。我更推荐把params方法默认视为只读，需要修改时显式传入数组并用返回值或out表达意图。

2.4 重载决策：编译器为什么更偏爱“不展开”的版本

假设你写了两个重载：

static void Print(string s) { Console.WriteLine(s); } static void Print(params string[] ss) { foreach (var s in ss) { Console.WriteLine(s); } }

调用Print("hello")时，编译器会选择Print(string)，而不是Print(params string[])。为什么？因为 C# 的重载决策规则里，普通参数形式被认为比params展开形式更具体、更优先。只有当普通重载无法匹配时，编译器才会考虑把实参展开成数组来匹配params版本。

所以调用Print("a", "b")会走params版本，而调用Print("hello")会走单参数版本。这个规则在很多公共 API 里被刻意利用：单参数高频调用走固定重载，多参数才走params重载，既方便调用方又能减少数组分配。后面性能章节会再讲它的意义。

但这里也埋了一个雷：当参数是null时，编译器会认为Print(null)既可以匹配Print(string)也可以匹配Print(params string[])，导致编译报“调用不明确”的错误。解决办法是用强转：

Print((string)null); Print((string[])null);

这个细节会在避坑章节专门解释。

3.1 那些你天天写却不知道是 params 的 API

打开 .NET 源码，你会发现params的身影出现在大量基础方法里。最典型的是Console.WriteLine的格式化重载：

Console.WriteLine("订单 {0} 已支付 {1:C}", 1024, 99.9);

它的其中一个重载签名是WriteLine(string format, params object?[] arg)。再比如string.Format：

string message = string.Format("用户 {0} 在 {1} 登录", userName, time);

还有string.Join，很多版本的重载就是Join(string separator, params object[] values)或Join(char separator, params string[] values)。以及路径拼接的Path.Combine(params string[] paths)，用过它的人应该能直观感受到：如果没有params，写多个路径拼接时还得先去构造数组，代码会冗长不少。

这些 API 的共性是什么？它们的参数数量在业务层面本来就是未知的：一条日志要拼几个变量？一个路径要几层？一个集合要格式化几项？没人能提前确定。这正是params真正的用武之地，而不是“为了少写几个重载”。

3.2 自己动手写一个日志封装，为什么用 params object[]

理解了内置 API 的写法，我们照猫画虎写一个简易日志封装：

public static class Log { public static void Info(string format, params object[] args) { string message = args == null ? format : string.Format(format, args); Console.WriteLine($"[INFO] {message}"); } }

调用方式非常自然：

Log.Info("用户 {0} 执行了 {1}", 1024, "下单"); Log.Info("系统已启动"); Log.Info("任务完成，耗时 {0} ms，结果 {1}", duration, result);

注意第二行只传了format，没有传任何args。此时args是空数组，string.Format(format, args)依然安全，因为格式化字符串里也没有占位符。这就是为什么params object[]适合做日志这类形态不确定的参数：调用方可以完全不传附加参数，也可以传任意多个。

为什么是object[]而不是string[]或强类型数组？因为日志参数可能是数字、枚举、对象、异常信息，把任意类型塞进object[]是最通用的方案。代价是值类型参数会发生装箱，这个问题我会在第四章专门讨论。

3.3 string.Format 的参数机制：params 只是“搬运工”，不是“格式解析器”

很多入门者会把string.Format的 params 特性和占位符解析混为一谈，以为params负责把{0}、{1}替换成对应值。这是误解。params做的事仅仅是把调用方的多个实参打包成一个object[]，传递到string.Format方法内部。至于这个数组里的第几个元素对应哪个占位符，是由string.Format内部用格式化逻辑去解析的。

所以当你写出：

string s = string.Format("{0}{1}", 1); // 运行时抛 FormatException

这个抛异常与params无关，而是string.Format发现数组里只有一个元素，但格式化字符串里出现了两个占位符。params在这里只是一个“运输容器”，理解了这条边界，你就不会在调试这种问题时绕圈子。

4.1 不管传几个参数，数组几乎总要被创建

一个被很多人忽略的事实是：调用Sum(1)这种只有一个参数的params调用，编译器依然会在调用点创建一个长度为 1 的数组。换句话说，params不是零成本的特性，它把“创建数组”的负担从调用方代码转移到了运行时。

创建数组本身有两个开销：一是内存分配，二是后续 GC 回收。低频调用可以完全无视，但如果这个方法被放到一个 100 万次循环里，那就意味着百万级别的数组分配。即使每个数组都不大，GC 的压力也是实打实的。某些运行时对空数组和一小部分小数组有缓存优化，但这是实现细节，不是 C# 语言规范承诺的行为。在写性能敏感代码时，默认“每次调用都会分配”是最稳妥的假设。

params object[]的物理分配分成两块：数组本身，以及装入数组的值类型元素。例如调用：

Log.Info("数量: {0}, 单价: {1}", 5, 9.9m);

5和9.9m都会装箱成object，然后再被放进object[]。所以一句话总结：传 N 个值类型参数，产生的额外对象是 1 个数组加 N 个装箱对象。在循环里调用这种 API，垃圾回收会非常酸爽。

强类型params就没有这个烦恼：

static void PrintNumbers(params int[] nums) { }

PrintNumbers(1, 2, 3)只会创建一个int[]，数组内存储的是未装箱的整数。所以我的原则很简单：能写强类型params就写强类型，不要默认params object[]万能。

4.3 高频循环的优化手段：用重载剥离掉数组分配

前面章节提到的“非 params 重载优先”正好可以用来做性能优化。假设你有一个需要高频调用的加法方法：

static int Add(params int[] nums) { int sum = 0; foreach (var n in nums) sum += n; return sum; }

如果内部循环里大量使用Add(1, 2)，每次都会分配数组。此时提供固定参数重载：

static int Add(int a, int b) => a + b; static int Add(params int[] nums) { int sum = 0; foreach (var n in nums) sum += n; return sum; }

调用Add(1, 2)时，编译器会优先选择非 params 的Add(int, int)，从而零数组分配；而偶尔传 3 个、4 个甚至更多参数时，依然由params重载兜底。这是 .NET 内置 API 惯用的伎俩：Console.WriteLine就同时存在单参、双参、三参以及params object[]的重载，高频路径用固定重载避开数组分配。你在设计自己的类库时，完全可以把这套方案复制过去。

4.4 一个粗粒度的分配对比思路

你可以在自己的项目里跑这样一段监测代码，感受params的开销：

long before = GC.GetAllocatedBytesForCurrentThread(); for (int i = 0; i < 1_000_000; i++) { Add(1, 2, 3); } long after = GC.GetAllocatedBytesForCurrentThread(); Console.WriteLine($"分配了 {after - before} 字节");

如果只有Add(params int[])这一个重载，这 100 万次调用会对应 100 万个临时数组，也就是说至少百万级别的分配对象数量。换成“二参固定重载 + 三参以上 params”的组合后，Add(1, 2, 3)依然会走 params，如果想规避，你还得再加一个三参重载。实际开发中不需要把每个参数个数都写一遍，更合理的思路是用非 params 重载覆盖最高频的少数场景，其余走兜底。

再说一个容易被忽略的点：如果你已经有一个可复用的数组，直接以数组形式传入params方法，编译器不会复制它。比如：

int[] prebuilt = { 1, 2, 3 }; Sum(prebuilt); // 直接传引用，不新建数组

在循环里可以预先构建一次数组，然后反复传入，减少反复分配。但这种做法要求方法内部不能修改数组内容，否则你会把一个被复用数组改得面目全非，这也是取舍。

5.1 params 与泛型组合：既能保持强类型，又保留可变数量

初学者常有一个疑问：params能不能用在泛型方法里？答案是完全可以，而且这是很实用的组合：

static void Echo<T>(params T[] args) { foreach (var a in args) { Console.WriteLine(a); } }

调用时会发生泛型类型推断：

Echo(1, 2, 3); // T = int Echo("a", "b"); // T = string Echo(1, "a"); // 缓存可选，regex缓存，组合推断

当参数类型混合时，编译器会推断 T 为它们的公共基类，多数情况下是object，于是值类型元素会装箱。所以泛型params的真正价值在于：当调用方的所有参数都是同一种类型时，可以保留强类型参数数组，避免装箱。例如一个专属日志工具需要记录一堆时间戳，就可以是LogTimestamps(params DateTimeOffset[] stamps)，这样数组内不装 object，性能更好。

5.2 数组作为单个参数传入 params 的隐藏歧义

params object[]这个方法本身接收一个对象数组，但如果你传入一个数组，编译器很可能把它当成“可变参数展开”而不是“数组本身作为单个对象”。看例子：

static void Print(items lengths??) { foreach (var item in args) { Console.WriteLine(item); } } int[] arr = { 1, 2, 3 }; Print(arr); // 传入 3 个 int 元素（每个都装箱） Print((object)arr); // 只传入 1 个元素，这个元素是 int[]

Print(arr)因为arr是int[]，编译器理解成“把三个元素展开后作为三个实参传入”，于是args里存在三个装箱后的int。而Print((object)arr)，因为实参类型变成了object，不再满足“数组展开”的条件，就作为单个对象整体进入params数组。如果你确实想把一个数组当作单个元素传入，也可以这样写：

Print(new object[] { arr });

这与(object)arr等价。这类歧义在你调用别人设计的params object[]方法时尤其容易踩到，尤其是string.Format场景中想格式化输出一个数组时，要先确定你想要的到底是一整行数组内容，还是数组展开后的若干元素。

5.3 调用 Foo(null) 时的重载歧义和警告

如果一个方法只有params string[]版本：

static void Foo(params string[] args) { }

然后调用Foo(null)，编译器会弹出警告，因为它无法判断null到底想表达什么：是想传一个空数组，还是想把null字符串作为数组的单个元素，还是把一个 null 字符串数组直接传进去。在可空引用类型上下文里，这个问题会更明显。

更糟的是同时存在重载：

static void Foo(string s) { } static void Foo(params string[] ss) { }

此时Foo(null)会直接变成编译错误：调用不明确。因为null既可以转换为string，也可以转换为string[]，编译器不知道选哪个重载。解决办法是显式指定类型：

Foo((string)null); Foo((string[])null);

如果方法内部希望把 null 数组统一视为空，就判空后替换：

static void Foo(params string[] ss) { ss ??= Array.Empty<string>(); // 后续逻辑 }

Array.Empty<string>()返回一个共享的空数组，比new string[0]更省，这也是写 params 方法时值得养成的习惯。

5.4 params 与 ref/out/in 不能组合，二维数组也不行

这条规则在实际编码中体现为编译错误。为什么不能组合？ref和out要求调用方传入变量的引用，而params的本质是“可变数量的实参”被打包成数组，若数组里的元素同时还要持有外部变量的引用，调用约定就会变得诡异且难以验证。in同理，它也是引用语义的参数修饰。

至于多维数组，从语法层面看它符合“数组”的字面意思，但编译器只接受一维数组作为params。这和你用int[][]作为普通参数并不冲突，只是不能用于可变参数展开。如果你确实需要传递一组坐标点，就把每个坐标点封装成类或结构体，再用params Point[]，这样既清晰又满足一维数组的要求。

5.5 空数组检查的推荐写法

一个完整的 params 方法，我建议从第一行就开始做防御：

static void Handle(string title, params int[] nums) { nums ??= Array.Empty<int>(); // 正常业务逻辑 }

这样无论调用方传Handle("标题")、Handle("标题", 1)还是Handle("标题", null)，方法内部都可以安全地遍历nums。这种习惯在团队协作时尤其重要，因为你无法控制调用方是否会传null，一行??=就能避免一次线上空引用事故。

如果你想让调用方显式使用“零个参数”的语义，更推荐的方法是把参数设计成IEnumerable<int>而不是数组合适吗？注意params不能修饰IEnumerable，这是 C# 13 之前的事实。所以数组仍是默认选择。

6.1 为什么 C# 13 要放开 params 的类型限制

聊到性能，很多对 C# 熟悉的朋友最痛的一点是：params只能修饰数组，导致即使只传两三个参数，也会在堆上生成一个数组对象。若是在栈上使用临时数据，这显得很不划算。C# 13 的params collections特性正是冲着这个问题去的，它允许params参数使用Span<T>、ReadOnlySpan<T>以及支持集合表达式的集合类型，编译器可以借用栈上的临时存储或现有集合，避免额外堆分配。

一个简单的示例：

static void PrintAll(params ReadOnlySpan<string> names) { foreach (var name in names) { Console.WriteLine(name); } } PrintAll("a", "b", "c");

在这个版本里，调用点不会像数组params那样强制产生一个托管数组，而可能直接使用一组栈上持久数据，传递过程更轻便。这个特性需要 .NET 9 以及支持 C# 13 的编译器，旧项目若锁定旧框架则无法使用。

6.2 一个可以立刻用起来的新写法

在 .NET 9 项目里，你可以这样写求和函数：

static int Sum(params ReadOnlySpan<int> numbers) { int total = 0; foreach (var n in numbers) { total += n; } return total; }

调用方式与以前完全一样：

int result = Sum(1, 2, 3, 4, 5);

新的实现方式并不要求调用方改变什么，这就是兼容性的好处。但要注意，ReadOnlySpan<T>不能替代所有场景：如果你需要把参数数组保存为字段、传给异步方法或跨越await边界，Span 的限制就会显现出来。异步方法中不能使用Span作参数，因此这类场景仍然要回到数组版本。

6.3 新旧代码迁移时的取舍

把现有params int[]改成params ReadOnlySpan<int>是签名变更，虽然调用点源码一般不用动，但对于一些通过反射查找方法、依赖params元数据的工具来说，可能带来不兼容。我的建议是：新项目、内部工具、明显的高频路径，可以大胆用新特性；对外发布的公共 API 要更谨慎，至少等目标平台确定不会再回退，再迁移，否则一次签名调整可能让下游使用者陷入编译问题。也可以采用“双版本并存”策略，固定重载用于高频，params 数组版本用于兼容，新的 Span 版本再作为内部热路径使用。

关于params，我自己的习惯是把它当成“数量不确定的参数容器”来看待，而不是用来花哨地替代正常参数。设计 API 时，先问一句：参数数量在业务上真的不确定吗？如果是，params 是正确答案；如果只是为了少写几个重载，那它只会增加调用端的模糊性和重载歧义。另一个实用的经验是：每个 params 方法内部一定要对参数数组做空保护，同时约定“空数组”或“null 数组”到底代表什么；调用端则尽量不传null，保持意图明确。这样，这个修饰符才能既优雅，又不出幺蛾子。