函数模板是C++泛型编程的基础工具，它让同一段逻辑可以适配多种类型。但在实际工程中，模板带来的灵活性也伴随着不少隐蔽问题。很多编译错误和运行时行为异常，并不是业务逻辑写错，而是对模板的推导规则和实例化机制理解不够深入。
类型推导与引用带来的陷阱
函数模板最容易被忽视的问题之一，就是类型推导在遇到引用和常量性时的行为。当我们把参数声明为T&或const T&时，编译器推导出的T类型会包含或去掉引用与限定符，这和普通函数的参数传递并不完全相同。
例如下面的模板函数，本意是交换两个变量，但如果传入的是字面量或临时对象，就会因为左值引用无法绑定而编译失败。更麻烦的是，若使用转发引用T&&，在模板中推导规则又变成引用折叠，新手极易写出错误代码。
#include <iostream>
using namespace std;
template <typename T>
void swap_val(T& a, T& b) {
T tmp = a;
a = b;
b = tmp;
}
int main() {
int x = 1, y = 2;
swap_val(x, y); // 正确，T推导为int
// swap_val(1, y); // 错误，1是右值不能绑到int&
return 0;
}
上面的代码在注释行会直接编译报错。如果希望同时支持左值和右值，应当使用std::forward配合转发引用，但这又引入了新的复杂度：你必须清楚完美转发的适用边界，否则可能把临时对象的生命周期管理搞乱。
此外，当数组名传入T&模板参数时，T会被推导为数组类型而非指针，这和普通函数退化为指针的行为不同。这种差异会让模板特化和重载决议产生令人意外的结果。
模板特化与重载决议冲突
函数模板支持全特化，但不支持偏特化，而普通函数重载又与模板重载交织在一起。编译器在挑选调用目标时，遵循一套复杂的优先级规则：非模板函数优先于模板，特化版本优先于主模板，但更特化的模板不一定总被选中。
看下面这个例子，我们为指针类型提供一个特化，同时还有一个普通重载：
#include <iostream>
using namespace std;
template <typename T>
void print(T v) {
cout << "template: " << v << endl;
}
template <>
void print<int*>(int* v) {
cout << "spec ptr: " << *v << endl;
}
void print(int* v) {
cout << "normal ptr: " << *v << endl;
}
int main() {
int a = 5;
print(&a); // 调用普通函数，而非特化
return 0;
}
运行结果显示调用的是普通函数版本。因为根据重载决议，非模板函数比模板特化匹配度更高。如果删掉普通函数，才会落到特化版本。这种规则常让维护者误以为特化一定会生效，实则不然。
当项目中有多个头文件分别定义了相似模板和重载，且包含顺序不同时，同一个调用点可能在不同编译单元解析出不同函数，造成难以排查的一致性问题。因此团队中应约定模板扩展方式，减少随意特化。
非类型模板参数与代码膨胀
函数模板除了类型参数，还可以有非类型参数，比如整数或指针。这类参数必须在编译期确定，且不同值会生成完全不同的函数实例，进而引发代码体积膨胀。
以下代码用非类型参数控制缓冲区大小：
#include <iostream>
using namespace std;
template <typename T, int N>
void fill_zero(T (&arr)[N]) {
for (int i = 0; i < N; ++i) arr[i] = 0;
}
int main() {
int a[10];
double b[20];
fill_zero(a); // 实例化 fill_zero<int,10>
fill_zero(b); // 实例化 fill_zero<double,20>
return 0;
}
虽然写法很方便，但每个不同的N都会产生一份独立机器码。在嵌入式或大型项目中，过多这类实例化会明显增加二进制尺寸。若能用普通函数加运行时参数替代，往往更节省空间。
另外，非类型模板参数不支持某些类型，如浮点数和类对象（C++20前），这限制了使用场景。若强行用类型标签模拟，又会降低可读性。设计接口时要权衡编译期约束与维护成本。
模板定义在头文件中的链接陷阱
模板通常必须写在头文件中，因为编译器需要在实例化点看到完整定义。如果误把模板实现放进cpp文件，链接时会报未定义符号。但即便都写在头文件，若两个编译单元以不同方式特化同一模板，也可能出现_ODR（单一定义规则）违规。
比如一个头文件里放了函数模板，另一个地方用了显式实例化，而某源文件又隐式实例化出另一版本，链接器可能选错实现。这类问题不会在单个文件编译时报错，只在最终链接或运行时显现。
// math_util.h
template <typename T>
T add(T a, T b) { return a + b; }
// a.cpp
#include "math_util.h"
template int add<int>(int, int); // 显式实例化
// b.cpp
#include "math_util.h"
int use() { return add(1, 2); } // 隐式实例化，可能与显式不一致若定义改动
为避免此类问题，显式实例化声明应集中管理，并且保证所有编译单元看到的模板定义完全一致。现代构建系统也建议开启模块化或统一头文件包含检测。
综合来看，函数模板的陷阱大多来自编译期机制与开发者直觉之间的偏差。掌握类型推导、重载决议、实例化模型和链接规则，才能把泛型能力用得稳妥。