第一次见到ColumnTransformer时，我的第一反应是：这不就是 sklearn 里的一个组合工具，把几个预处理变换塞进一个列表里吗？真正被它救了一次之后，我才意识到这个工具解决的，根本不是“代码少写几行”的问题，而是把整个表格型机器学习项目的预处理流程，从一团手写脚本变成了一根可以复用、可以交付、不会悄悄出错的管道。
很多人在做表格数据时都会经历这样的阶段：先手动筛选数值列，做缺失值填充、标准化；再手动筛选类别列，做独热编码；训练集跑通了，再对测试集重复一遍同样的操作。看起来没毛病，但一旦要调参、要交叉验证、要部署，这套手工流程就会成为最大的隐患。因为只要有一个步骤的顺序错了，一个变换器的参数只在训练集上 fit 了，或者测试集少处理了一列，模型的表现就会莫名其妙地崩掉，而且非常难排查。
ColumnTransformer就是为了终结这种手工拼装而产生的工具。这篇文章会从它解决的问题出发，讲清楚它的核心机制、从零到一的落地流程、嵌套用法，以及最容易踩的坑。
1. 先搞明白：你真正要解决的，不是“怎么同时变换多列”
很多教程把ColumnTransformer解释成“一个可以对不同列应用不同变换的工具”。这个说法没有错，但它太保守了。如果只是为了“对不同列做不同处理”，你完全可以写几个函数分别处理，然后再pd.concat拼回来。真正让ColumnTransformer变得不可替代的，是它把“预处理”这个动作变成了一台有状态、有顺序、可以被整体搬运到训练和推理阶段的机器。
1.1 手工预处理的最大风险，不是代码难看，而是数据泄露
你在网上看到的很多入门代码是这样的：
# 手工预处理流程（常见但危险的写法） from sklearn.preprocessing import StandardScaler, OneHotEncoder from sklearn.model_selection import train_test_split import pandas as pd X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2) # 先对整个数据集做填充或缩放，再切分？还是先切分再处理？ # 不同教程写法不一样，很容易把 fit 用在全量数据上 scaler = StandardScaler() X_train_scaled = scaler.fit_transform(X_train) X_test_scaled = scaler.transform(X_test) encoder = OneHotEncoder(handle_unknown='ignore') X_train_encoded = encoder.fit_transform(X_train[['city']]) X_test_encoded = encoder.transform(X_test[['city']])表面上看，训练集和测试集的处理逻辑是一致的：先 fit 训练集，再 transform 测试集。但真实项目的处理链条远比这个长，一旦加入缺失值填充、异常值裁剪、特征衍生、标准化、独热编码，五个步骤里有任何一个步骤不小心用fit_transform处理了整份数据，数据泄露就发生了。
数据泄露的后果是：交叉验证分数虚高，模型上线后效果断崖式下跌。而且这种错误在代码里很难发现，因为检测过程不会直接报错。
ColumnTransformer之所以重要，不是因为它能拼多个变换器，而是因为它把“每个变换器必须只在训练数据上 fit，再对测试数据 transform”这个规则，固化到了工具的底层逻辑里。当你把ColumnTransformer放进Pipeline后，每一折交叉验证都会重新走一遍 fit 和 transform，全量数据根本进不到预处理环节。
1.2 你其实需要的是一个“可复用的预处理流水线”
再看另一个场景：你今天处理完训练集和测试集，生成了模型。两周后，新的线上数据进来了，你要怎么做？如果你手写预处理脚本，你需要找到当时的代码、当时的列名、当时的参数，然后把那五六步再执行一遍。只要有一个参数变了，结果就完全不一样。
ColumnTransformer的长期价值就在这里：它把预处理变成对象。你可以在训练结束后把整个ColumnTransformer（更完整的是把包含它的Pipeline）保存下来，线上一条新数据进来，直接调transform或者predict，所有填充、编码、缩放逻辑自动执行。这才是它和“手动拼装”之间真正的分水岭。
2. ColumnTransformer 到底做了什么？它的边界在哪？
理解ColumnTransformer，核心是理解它的三个设计：transformers列表参数、remainder剩余列处理策略、以及set_output输出格式控制。这三个点分别对应“对哪些列做什么变换”“没被选中的列怎么办”“输出结果是什么形式”。
2.1 transformers 列表：用声明的思路定义变换
一个最基本的ColumnTransformer写法如下：
from sklearn.compose import ColumnTransformer from sklearn.preprocessing import StandardScaler, OneHotEncoder preprocessor = ColumnTransformer( transformers=[ ('num', StandardScaler(), ['age', 'income']), ('cat', OneHotEncoder(handle_unknown='ignore'), ['city', 'education']) ] )这个参数结构非常像一张配置表。每个元组的三个元素分别表示：这一步叫什么名字、用什么变换器、作用在哪几列。这样做的好处是，你看代码就能判断出整个预处理策略，而不是在几十行手动脚本里猜。
但要注意，transformers里的变换器必须是“有 fit 和 transform 方法的对象”，也就是说，它得是一个 sklearn 风格的估计器或变换器。如果你有自己的处理逻辑，比如要写一个取 log 的自定义函数，建议包装成FunctionTransformer或者自定义一个TransformerMixin类，再放进去。
2.2 remainder：没被选中的列，是丢掉还是保留？
这是新手最容易困惑的地方。ColumnTransformer默认情况下，只处理transformers里明确列出的列，其他列会被丢弃。如果你有特征 ID 列、文本内容列、或者只是暂时不想处理的列，会直接被丢掉。
# 保留所有未指定列，原样透传 preprocessor = ColumnTransformer( transformers=[ ('num', StandardScaler(), ['age', 'income']) ], remainder='passthrough' )remainder有三个常用取值：
| 取值 | 行为 | 适用场景 |
|---|---|---|
'drop' | 默认值，丢弃未指定列 | 明确只保留某些特征，其余都无用 |
'passthrough' | 未指定列原样保留，不缩放、不编码 | 有 ID 列或已经处理好的数值特征 |
| 某个变换器对象 | 对未指定列应用另一个变换流程 | 想对剩余列统一做填充或标准化 |
如果把remainder设置为'passthrough'，输出列会按照“先 transformers 中处理后的列，再剩余列”的顺序拼接。如果你后续要用get_feature_names_out()查看列名，这一点会非常明显。
2.3 输出格式：为什么有人拿到的是数组，有人拿到的是 DataFrame
ColumnTransformer的输出默认是 NumPy 数组或稀疏矩阵。如果你把OneHotEncoder放进去，类别列编码后很可能是稀疏矩阵。此时你会遇到一个问题：明明输入的是一份带列名的 DataFrame，transform 之后却变成了没有列名的矩阵，调试时很难受。
现代 sklearn（1.2 以后）提供了一个统一的输出控制接口：
preprocessor.set_output(transform='pandas') df_transformed = preprocessor.fit_transform(X_train)这样得到的就直接是 DataFrame，列名会自动生成。这个功能在日常调试和查看中间结果时非常有用，但需要注意两点：第一，老版本不支持set_output；第二，如果你的变换流程里有老版本的自定义类，没有实现get_feature_names_out，输出列名可能生成失败。
3. 从零到一的落地流程：先跑通单个变换，再组合完整管道
这一节我们走一个完整的例子。假设你有一份简单的用户信息表，包含数值特征、类别特征和缺失值。目标是训练一个逻辑回归模型。
我先说明一点：下面的数据和代码都是为了演示结构，不是某份真实业务数据。
3.1 环境准备和数据构造
你需要安装scikit-learn、pandas、numpy。版本上建议 sklearn 不低于 1.2，因为会用到set_output和更稳定的get_feature_names_out行为。
pip install scikit-learn pandas numpy然后构造一份示意数据：
import pandas as pd import numpy as np df = pd.DataFrame({ 'age': [25, 32, 47, np.nan, 28], 'income': [50000, 62000, 80000, 90000, 45000], 'city': ['北京', '上海', '广州', '北京', '上海'], 'education': ['本科', '硕士', '博士', '本科', '硕士'], 'label': [0, 1, 0, 1, 1] }) X = df.drop('label', axis=1) y = df['label']这份数据非常小，只是为了让你能看清每一步的输入输出。真实项目里，你只需要保证X是一个带列名的 DataFrame 即可，数值列和类别列可以混排。
3.2 第一个版本：数值列标准化 + 类别列独热编码
先把最简单的流程跑通：
from sklearn.compose import ColumnTransformer from sklearn.preprocessing import StandardScaler, OneHotEncoder numeric_features = ['age', 'income'] categorical_features = ['city', 'education'] preprocessor = ColumnTransformer( transformers=[ ('num', StandardScaler(), numeric_features), ('cat', OneHotEncoder(handle_unknown='ignore'), categorical_features) ] ) X_transformed = preprocessor.fit_transform(X) print(X_transformed.shape)这里fit_transform的输入是X，一个 DataFrame。因为当前没有切分训练测试，所以直接用全量数据做演示。真正建模时，一定要把它放进Pipeline，让fit和transform在交叉验证内部自动执行。
3.3 无缝拼接：把 ColumnTransformer 放入 Pipeline
只做预处理还不够。你应该把预处理和模型放进同一个Pipeline：
from sklearn.pipeline import Pipeline from sklearn.linear_model import LogisticRegression from sklearn.model_selection import train_test_split X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42) model = Pipeline([ ('preprocessing', preprocessor), ('classifier', LogisticRegression(max_iter=1000)) ]) model.fit(X_train, y_train) score = model.score(X_test, y_test) print(score)这一步非常关键。当你使用Pipeline时，每一次调用fit，都会先执行preprocessing.fit_transform(X_train)，再对X_test执行transform。也就是说，标准化中的均值和标准差、独热编码的类别列表，都是从训练集学到的，测试集只被转换，不参与 fit。
如果你单独在外面先fit_transform全量数据再切分，数据泄露的风险就会立刻出现。
3.4 查看中间结果：列名和输出格式
调试时我建议打开输出格式，方便看清楚每一列是什么：
preprocessor.set_output(transform='pandas') X_transformed = preprocessor.fit_transform(X) print(X_transformed.head()) print(X_transformed.columns.tolist())输出列名大概是这样的结构：
['num__age', 'num__income', 'cat__city_北京', 'cat__city_上海', 'cat__city_广州', 'cat__education_博士', 'cat__education_本科', 'cat__education_硕士']num__age表示这一步叫num、原始列是age。这种命名方式在排查特征时非常友好。
注意：如果后面要接模型，
set_output(transform='pandas')不是必需的。但如果你要查看中间特征、做特征重要性分析、或者把预处理结果导出，我建议开启它。
4. 进阶用法：让它真正适配复杂的真实数据
拿真实数据做项目时，你会发现一个ColumnTransformer里的 transform 列表往往不会只有标准化和独热编码。这里讲几个最常见的进阶场景。
4.1 在变换器内部嵌套 Pipeline，处理多步骤预处理
假设age列有缺失值，你希望先填充中位数，再标准化；city列缺失值很少，但你想填充众数，再独热编码。如果只在ColumnTransformer里放一个SimpleImputer，你是没法直接完成“先填充再标准化”的。因为transformers列表里每个位置实际上只能放一个变换器对象。
解决办法：在这个位置上放一个Pipeline。
from sklearn.impute import SimpleImputer from sklearn.pipeline import Pipeline preprocessor = ColumnTransformer( transformers=[ ('num_clean', Pipeline([ ('imputer', SimpleImputer(strategy='median')), ('scaler', StandardScaler()) ]), ['age', 'income']), ('cat_clean', Pipeline([ ('imputer', SimpleImputer(strategy='most_frequent')), ('encoder', OneHotEncoder(handle_unknown='ignore')) ]), ['city', 'education']) ] )这样就实现了分步预处理。注意内层 Pipeline 的列作用域已经由外层ColumnTransformer限定了，所以内层 Pipeline 里的每个变换器，作用范围都是['age', 'income']或['city', 'education']，不需要重复指定列名。
这就是为什么说ColumnTransformer不是“多个变换器的列表”，而是一个可以嵌套任意复杂流程的容器。
4.2 自定义变换器：把业务规则也纳入管道
真实项目里经常有这样的需求：某个特征要做 log1p 转换，某个特征要按业务规则裁剪异常值，某个特征要组合出新特征。这些逻辑如果写在ColumnTransformer外面，又会退回“手动拼装”的老路。
更稳的做法是把它们包装成标准的变换器：
from sklearn.base import BaseEstimator, TransformerMixin import numpy as np class Log1pTransformer(BaseEstimator, TransformerMixin): def fit(self, X, y=None): return self def transform(self, X): return np.log1p(X)然后放进ColumnTransformer：
preprocessor = ColumnTransformer( transformers=[ ('num_scale', Pipeline([ ('imputer', SimpleImputer(strategy='median')), ('scaler', StandardScaler()) ]), ['age', 'income']), ('log_income', Log1pTransformer(), ['income']), ('cat_clean', OneHotEncoder(handle_unknown='ignore'), ['city', 'education']) ] )需要注意的是，这里income同时出现在了num_scale和log_income两个变换器里。ColumnTransformer允许你这么做，输出时会同时保留两份income的衍生特征。这个特性有时候是优点（你可以保留原始尺度、对数尺度两种特征），有时候是坑（你不小心重复处理了一列，导致特征冗余）。实际操作时，建议先确认自己是否需要同时保留两版，避免无意识的重复。
4.3 和网格搜索配合：让预处理参数也参与调参
ColumnTransformer里的变换器参数，同样可以被网格搜索调参。比如SimpleImputer用median还是mean，OneHotEncoder是否handle_unknown='ignore'，这些都可以通过参数名前缀来指定。
from sklearn.model_selection import GridSearchCV param_grid = { 'preprocessing__num_clean__imputer__strategy': ['mean', 'median'], 'classifier__C': [0.1, 1, 10] } grid_search = GridSearchCV(model, param_grid, cv=3) grid_search.fit(X_train, y_train)参数前缀和你在Pipeline里定义的步骤名完全一致。这种写法比手动写循环去测试不同预处理方式要清晰得多。而且网格搜索的每一折交叉验证，都会在训练折内重新 fit 预处理变换器，所以不会把验证折的信息提前泄露进填充或缩放过程中。
4.4 部署时：保存的是整个 Pipeline，而不是中间产物
很多人的误区是，模型部署时只保存了模型权重，然后在新数据进来时，重新写代码做预处理。如果用了ColumnTransformer，你应该保存整个Pipeline。
import joblib joblib.dump(model, 'model_with_preprocessing.pkl')线上使用时直接加载这个Pipeline，对它调用predict，预处理和模型会按顺序自动执行。这样你就不需要在新环境里重新定义哪些列要填充、哪些列要独热编码、哪些列要标准化了。
5. 最容易翻车的不是代码逻辑，而是这些隐藏问题
工具本身不难，难的是你不知道它会在哪个环节给你埋雷。下面这几个问题是我在实际使用中反复遇到的，按排查频率排序。
5.1 报错“Input contains NaN”：缺失值没有被处理
症状很直接：fit或transform时提示输入包含 NaN。很多人第一反应是缺了SimpleImputer，但不全对。常见场景是：SimpleImputer只放在数值列上，但类别列里也有缺失值；或者remainder='passthrough'透传了某个含缺失值的列。
排查顺序：
- 检查
transformers里每个变换器的列是否覆盖了所有含缺失值的列。 - 检查
remainder是否把某个含缺失值的列透传了进来。 - 用
X.isna().sum()先看看每列缺失数量。
5.2 输出特征数量和你预期不一致
特征数量不对，通常有两类原因。
第一类：OneHotEncoder对类别列的编码结果和预期不同。比如类别列里有训练集没出现过的新类别，如果没有设置handle_unknown='ignore'，transform 时会直接报错。
第二类：remainder的策略不对。默认'drop'会丢弃未指点列；如果你以为“写了transformers之外的列会自动保留”，就会少了很多特征。
查看特征名是最直接的排查法：
preprocessor.set_output(transform='pandas') X_transformed = preprocessor.fit_transform(X) print(X_transformed.columns.tolist())5.3 输出是稀疏矩阵，转换时报格式错误
当OneHotEncoder参与时，ColumnTransformer的输出可能是稀疏矩阵。大部分 sklearn 模型都支持稀疏输入，但如果你要在中间插入其他处理，比如自己写的函数，就要小心矩阵和数组的格式问题。
建议做法：在ColumnTransformer内部或外层设置set_output(transform='pandas')，让输出保持 DataFrame。如果老版本不支持，可以在 transform 之后主动np.asarray或toarray()。
5.4 特征名冲突：verbose_feature_names_out 带来的前缀
直接用get_feature_names_out()看输出列名时，你会发现 sklearn 默认给每个转换结果加了一个两步名前缀，比如num__age、cat__city_北京。
好处是避免两个变换器都输出同名特征时互相覆盖。副作用是列名带着__，某些下游工具不支持这种特殊符号。
preprocessor = ColumnTransformer( transformers=[...], verbose_feature_names_out=False )将这个参数设为False，输出列名就不会带步骤名前缀。但要注意：如果你的多个变换器恰好都会生成同名列，比如两个OneHotEncoder都生成unknown，那就会冲突。我自己通常会保留前缀，虽然难看但安全，后续可以通过列名后缀统一改名。
5.5 最容易忽略的：用 DataFrame 还是 NumPy 数组
ColumnTransformer对输入类型很敏感。如果你传入的是一个 NumPy 数组，它没有列名，那transformers第三项就只能用整数下标，比如[0, 1]，而不是['age', 'income']。一旦数据列顺序变了，整个预处理结果就错了。
我的建议是，只要使用ColumnTransformer，输入一律用带列名的 DataFrame。这能让你随意选择列名，而且代码可读性大大提高。
5.6 老版本兼容性：set_output 和 get_feature_names_out 不可用
set_output(transform='pandas')是比较新的功能，依赖 sklearn 1.2 以上。如果你的代码要在老版本环境里跑，就会直接报错。
排查方法：
import sklearn print(sklearn.__version__)如果版本过低，尽量避免依赖set_output，可以在ColumnTransformer外面手动转 DataFrame，或者把列名通过get_feature_names_out()拼回去。
6. 这套能力放到真实项目里的边界在哪？
工具再好，也有它的适用范围。谈边界不是为了劝退，而是为了让你知道什么时候可以用它，什么时候不用硬凑。
6.1 它真正适合的是“表格型数据的模型训练管道”
ColumnTransformer的典型位置，是在sklearn的Pipeline中充当特征工程层。最适合的场景是：原始数据是结构化表格，特征类型包括数值、类别、布尔、缺失值，目标是用逻辑回归、树模型、SVM 等 sklearn 模型做分类或回归。
它适合的消费者包括：
- 需要反复做交叉验证和网格搜索的人。因为
Pipeline + ColumnTransformer是防止数据泄露的标准结构。 - 需要把数据处理逻辑交付给他人或部署到线上的人。因为整个预处理被序列化成一个对象。
- 需要快速在多种特征处理方案之间做对比的人。因为切换变换器只需要改一行列表。
6.2 它不适合哪些场景？
第一，如果特征列很少、变换逻辑很简单，比如只有一列要做标准化、一列要做独热编码，你完全可以直接用Pipeline([('scaler', StandardScaler())])，没必要引入ColumnTransformer。它的复杂度只有在列类型混杂、处理步骤多的时候才会体现出价值。
第二，如果主要用的是深度学习框架，比如 PyTorch 或 TensorFlow，ColumnTransformer并不能直接参与训练。你可以用它做离线预处理，再把结果喂给神经网络，但大部分深度学习的表格数据 pipeline 都有自己的数据处理组件，硬把 sklearn 的预处理塞进去反而别扭。
第三，如果特征工程逻辑极其复杂，包含大量条件分支、循环、甚至依赖外部数据源，ColumnTransformer并不是最佳容器。它的结构本质上是“多个变换器按顺序并行作用于不同列”，过度复杂的数据流会超出它的表达能力。这时候你需要一个通用的自定义变换器，或者干脆用更灵活的数据处理框架，然后只把最终结果交给 sklearn。
6.3 什么时候你会真正感觉到它的长期价值
一个很典型的时间节点是：你的项目要复现模型，或者要迁移到另一台机器上重新推理。
如果你当初用的是手写预处理脚本，此时你要回忆一大堆东西：填充均值是多少？独热编码的列顺序是什么？测试集里遇到未见过的类别要怎么处理？
如果你用的是ColumnTransformer + Pipeline，只要你保存了模型文件，这些问题全部不存在。新环境里加载模型，对新数据直接调predict就行。
这也是我把它称为“把一次性预处理脚本升级为工程资产”的原因。它不会让单次运行的精度更高，但它能降低你把模型从实验环境推向真实环境时的不确定性。
现实里很多模型效果不好，不是算法选错了，而是数据在“训练时怎么处理的、线上时怎么处理的”这两套流程之间出现了偏差。
ColumnTransformer不是万灵药，但它至少让这两套流程收敛到同一套代码里。
6.4 从使用到维护：应该形成的一个最小习惯
最后给一个可执行的建议。无论项目大小，只要涉及 sklearn 的表格数据建模，我都会先写一个preprocessor，哪怕一开始只有一个变换器。原因很简单：从第一个人手写脚本开始，到后面维护、交接、线上推理，单例的ColumnTransformer成本极低，但它能强制整个流程按照“声明式配置 + 先 fit 后 transform”的模式运行。
如果你现在正被手写预处理脚本搞得心烦，可以先从最小版本开始：确定数值列和类别列，各挑一个变换器，把ColumnTransformer放进Pipeline里跑通，然后观察输出列名。你会发现，原来你需要的不是更多“处理技巧”，而是把已有的处理步骤用一个可复用的容器规范起来。
这个容器，就是你在接手任何表格型项目时，应该最先写下的那几行代码。
