1. 问题现场：一次看似矛盾的数据加载报错
先别急着改代码，我们把报错完整看一眼。最常见的形式长这样：
File "train.py", line 88, in <module> train_loader = DataLoader(train_dataset, batch_size=32, shuffle=True, sampler=sampler) ValueError: sampler option is mutually exclusive with shuffle这个报错不是程序运行到一半才崩的，而是在构造DataLoader的那一刻就抛出来了。也就是说，PyTorch在初始化数据加载器时做了参数合法性校验，发现你同时传了shuffle=True和一个自定义sampler，两者冲突，直接拒绝开工。
从报错本身来看，信息很直白：sampler和shuffle是互斥的，你不能同时使用。但很多小伙伴第一次遇到这个报错时，第一反应是“那我删掉shuffle=True不就行了？”——这话说对了一半，但如果你不理解背后的设计逻辑，删掉之后可能会踩进另一个坑：数据顺序不对、训练不收敛、类别分布失衡、甚至验证集指标虚高。
这篇文章就围绕这个报错，把sampler和shuffle的前因后果、源码逻辑、实际的解决思路和我在项目里踩过的坑一次讲清楚。不管你是刚入门PyTorch的新手，还是写了好几年训练脚本的老手，只要你还在跟DataLoader打交道，这篇内容都值得花几分钟看完。
顺便说一下，这个报错不只在PyTorch里出现。TensorFlow的tf.data、PyTorch Lightning的Trainer、Hugging Face的Trainer，在设计上都有类似的“互斥”约束。原理通了，换哪个框架都能快速定位。
2. 拆解报错背后的设计逻辑
2.1 为什么PyTorch要禁止shuffle和sampler同时使用
要理解这个限制，得先搞清楚shuffle到底是个什么东西。
在很多人的直觉里，shuffle=True就是“打乱数据顺序”，这个理解没错，但不够底层。在PyTorch的DataLoader源码中，shuffle=True这条路最终会走向一个名叫RandomSampler的采样器：
if shuffle: sampler = RandomSampler(dataset) elif sampler is None: sampler = SequentialSampler(dataset)也就是说，shuffle本质上不是一个独立于sampler之外的机制，它就是RandomSampler的一个快捷开关。当你写shuffle=True时，PyTorch内部其实帮你创建了一个RandomSampler，用随机索引的排列顺序来决定每个batch取哪些样本。
现在再看这个限制就清楚了：如果你同时传了shuffle=True和一个自定义sampler，PyTorch就面临一个“到底听谁的”的问题。是听shuffle的，创建一个随机的RandomSampler？还是听你的，用你传进来的sampler？代码没法替你决定，所以直接抛异常，把选择权交还给你。
这个设计不是PyTorch故意刁难人，而是为了避免歧义、保证行为可预测。如果你自己写一个训练框架，大概率也会做同样的参数校验——两个互相矛盾的指令同时进来，最安全的方式就是拒绝执行，而不是默默挑一个。
2.2 DataLoader的数据读取全流程
这里值得展开说一下DataLoader的完整数据读取链路，因为很多报错其实都跟这条链路上的组件有关。
一次完整的数据迭代大致是这样：
DataLoader拿着sampler，迭代出样本索引（一个Python整数列表或迭代器）。- 根据索引，从
dataset中取出对应的样本（调用__getitem__）。 - 多个worker并行读取时，
sampler负责给每个worker分配索引块，避免重复读取。 - 按
batch_size将样本聚合成一个batch。 - 如果设置了
collate_fn，用它对batch做进一步拼接、padding等处理。 - 产出这个batch给训练循环。
在这个链路里，sampler是第一步，它决定了“这一轮训练用哪些样本、以什么顺序用”。shuffle只是RandomSampler的一个配置开关，本质还是落在sampler这个环节上。
所以，当你需要自定义数据采样逻辑时（比如类别均衡采样、按权重采样、分布式采样），正确的做法是：构造一个Sampler子类实例，传给DataLoader的sampler参数，同时保证shuffle=False。这两者不是“都想用”，而是“只能二选一”。
2.3 常见触发场景
根据我在各种项目里看到的情况，这个报错最常见的触发场景有这么几类：
- 场景一：写了
shuffle=True，后来又因为需要类别均衡采样，加了一个WeightedRandomSampler，结果忘了把shuffle改成False。 - 场景二：从别人的代码里复制了一个
DataLoader的定义，原代码用了shuffle=True，你在此基础上加了sampler参数，没注意原来的shuffle还留着。 - 场景三：代码里用了一个变量来控制是否打乱数据，比如
shuffle=is_train，在某个分支里同时传入了sampler，导致训练时正常、验证时崩溃，或者反过来。 - 场景四：使用第三方库（比如Hugging Face的
Trainer），底层帮你构造了sampler，但你又在外层显式传了shuffle=True。
不管是哪种场景，核心矛盾都是同一个：两个控制采样顺序的开关同时被打开了。
3. 解决方案：从最简到最优雅
3.1 方法一：直接删掉shuffle参数（最快，但不一定对）
如果你只是想让代码跑起来，最快的办法就是删掉shuffle=True，因为自定义sampler本身已经决定了采样顺序：
# 修改前：报错 train_loader = DataLoader(dataset, batch_size=32, shuffle=True, sampler=my_sampler) # 修改后：不报错 train_loader = DataLoader(dataset, batch_size=32, sampler=my_sampler)这个改法没有问题，shuffle默认就是False，不传也没关系。但这里有个隐含风险：如果你的sampler并不是随机采样器（比如你传的是一个SequentialSampler或者自定义的固定顺序采样器），那么数据顺序就完全固定了。对于训练集来说，每一轮epoch的数据顺序都一样，模型可能会“记住”数据的排列顺序，导致收敛变慢或者泛化能力下降。
所以，删掉shuffle只是治标，你得想清楚：你的sampler是否已经在内部实现了随机化？
3.2 方法二：用sampler内部的随机性替代shuffle
很多自定义Sampler的__iter__方法里已经包含了随机逻辑。比如WeightedRandomSampler，它本身就是按权重做有放回随机采样，每一轮迭代都会重新生成一组随机索引，天然具备“shuffle”的效果：
sampler = WeightedRandomSampler(weights, num_samples=len(dataset), replacement=True) train_loader = DataLoader(dataset, batch_size=32, sampler=sampler)这种情况下，你根本不需要再额外设置shuffle=True，因为WeightedRandomSampler每次迭代产生的索引顺序都是随机的。如果画蛇添足再加一个shuffle=True，反而会报错。
再比如我自己实现的一个自定义采样器，思路是“先按类别分桶，再在桶内做随机，最后打乱桶的顺序”：
import torch from torch.utils.data import Sampler class BalancedSampler(Sampler): def __init__(self, labels, num_samples_per_class=32): self.labels = labels self.num_samples_per_class = num_samples_per_class self.class_to_indices = {} for idx, label in enumerate(labels): self.class_to_indices.setdefault(label, []).append(idx) def __iter__(self): indices = [] for class_indices in self.class_to_indices.values(): selected = torch.randint(len(class_indices), (self.num_samples_per_class,)) indices.extend([class_indices[i] for i in selected.tolist()]) # 最后再打乱一次 random.shuffle(indices) return iter(indices) def __len__(self): return self.num_samples_per_class * len(self.class_to_indices)这个采样器内部已经做了两轮随机化，所以传给DataLoader时同样不需要shuffle=True。
3.3 方法三：用DataLoader的generator参数控制随机性（推荐）
如果你担心自定义sampler没有内部随机逻辑，又想让每一轮epoch的数据顺序不一样，有个更优雅的方案：不传自定义sampler，而是用shuffle=True配合固定种子的generator。
import torch train_loader = DataLoader( dataset, batch_size=32, shuffle=True, generator=torch.Generator().manual_seed(42) )这个方案适合“只想打乱、不需要复杂采样策略”的场景。它不会触发ValueError，因为这里根本没有传sampler。同时，固定种子可以保证实验可复现。
但注意，这个方案解决不了类别不平衡、样本权重不均等问题，它只是单纯打乱顺序。
3.4 方法四：用SubsetRandomSampler替代shuffle
有一种场景是：你需要从数据集中随机抽取一部分数据作为训练集或验证集，同时希望数据顺序是随机的。很多人的第一反应是写shuffle=True，但如果你用的是SubsetRandomSampler，就完全不需要shuffle：
from torch.utils.data import SubsetRandomSampler indices = list(range(len(dataset))) random.shuffle(indices) train_indices = indices[:8000] val_indices = indices[8000:] train_sampler = SubsetRandomSampler(train_indices) val_sampler = SubsetRandomSampler(val_indices) train_loader = DataLoader(dataset, batch_size=32, sampler=train_sampler) val_loader = DataLoader(dataset, batch_size=32, sampler=val_sampler)SubsetRandomSampler每次迭代都会随机打乱传入的索引列表，所以用它就不需要再设置shuffle=True。如果设置了，同样会报错。
这种做法的好处是：训练集和验证集可以共用同一个dataset对象，通过不同的sampler来切分数据，内存开销更小，代码也更干净。
3.5 方法五：彻底理解“互斥”并主动设计
最后一种方案，其实是我个人最推荐的一种思路：把“是否shuffle”和“是否需要自定义sampler”当作两个正交的问题来考虑，然后主动做合并判断。
在实际写代码时，我一般会封装一个函数，专门负责构造DataLoader：
def build_dataloader(dataset, batch_size, shuffle=False, sampler=None, **kwargs): if sampler is not None and shuffle: raise ValueError("sampler and shuffle cannot be enabled at the same time") if sampler is not None: # 使用自定义采样器时，shuffle由采样器内部控制 shuffle = False return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle, sampler=sampler, **kwargs)这个封装看起来有点多余，但好处是：所有DataLoader的创建都走同一个入口，以后不管谁在代码里传了矛盾的参数，都能在第一时间暴露出来，而不是等到跑了半天才在某个隐蔽的地方报错。
4. 扩展：PyTorch Lightning和Hugging Face中的类似问题
如果你用的是PyTorch Lightning或者Hugging Face的Trainer，这个问题会以更隐蔽的形式出现。
4.1 PyTorch Lightning中的处理
Lightning的DataLoader通常写在train_dataloader()方法里。如果你在里面写了：
def train_dataloader(self): return DataLoader(self.dataset, batch_size=32, shuffle=True, sampler=self.sampler)一样会报错。但更坑的是，Lightning的Trainer在fit阶段会自动判断是否需要设置sampler（比如开启了分布式训练、或者启用了replace_sampler_ddp=True），它内部可能会强制替换你传入的sampler，这时候如果你还自己传了shuffle=True，报错就会在Trainer.fit()内部出现，定位起来更费劲。
我自己遇到过一次：代码在单卡上跑得好好的，一上多卡就报ValueError。排查了半天才发现，原来是Lightning在DDP模式下会创建一个DistributedSampler去替换我原来的采样器，而我原来的DataLoader里还保留着shuffle=True。
解决办法也很简单：把shuffle=True去掉，或者干脆把DataLoader的创建逻辑改为根据self.trainer.is_distributed动态决定。更进一步，如果你用的是Lightning 2.0以上的版本，建议直接把DataLoader的创建交给Lightning的自动机制，它内部会处理好sampler和shuffle的关系。
4.2 Hugging Face Trainer中的处理
Hugging Face的Trainer在训练时会根据args.dataloader_shuffle等配置自动构造DataLoader。同时，它在内部也会为分布式训练创建采样器。如果你在get_train_dataloader()里自己写了DataLoader又加了shuffle=True，有很大的概率跟内部逻辑冲突。
更关键的是，Trainer在构造DataLoader时会调用一个_get_sampler方法：
def _get_sampler(self, dataset, shuffle): pass # 内部逻辑会根据shuffle决定返回 RandomSampler 还是 SequentialSampler有些版本还会根据dataloader_persistent_workers、dataloader_num_workers等参数做额外处理。所以如果你在自定义的DataLoader里手动管理shuffle和sampler，很容易跟框架的逻辑打架。
我的建议是：Trainer场景下，尽量别自己手动构造DataLoader，而是把数据集的准备逻辑放在Dataset里，把采样策略通过data_collator、dataloader_sampler等参数交给Trainer管理。
5. 报错排查清单与实操经验
5.1 排查流程速查表
遇到这个报错，按以下顺序排查基本能定位问题：
| 步骤 | 检查项 | 处理方法 |
|---|---|---|
| 1 | 确认报错行是不是DataLoader(...)构造处 | 是，进入下一步；不是，往上找调用链 |
| 2 | 检查是否同时传了shuffle=True和sampler | 是，二选一 |
| 3 | 确认sampler是否来自第三方库或框架内部 | 是，检查框架是否会自动注入sampler |
| 4 | 确认shuffle是否来自某个变量（如is_train） | 是，检查变量值是否符合预期 |
| 5 | 确认代码是否被多次调用（如每个epoch重新创建DataLoader） | 是，检查每次调用传入的参数是否一致 |
这个表看起来简单，但在实际项目中，恰恰是第4和第5步最容易被忽略。我有一次排查了很久，最后发现是某个配置文件的shuffle字段被写成了字符串"True"，而不是布尔值True，导致判断逻辑出现奇怪的分支。
5.2 我踩过的三个典型坑
第一个坑：验证集也报错
我一开始只在训练集上加了类别均衡采样，验证集老老实实用shuffle=False，一切正常。后来重构代码时，把训练集的DataLoader和验证集的DataLoader封装到了一个函数里，参数名叫use_sampler。结果验证集也传了use_sampler=True，但对应的sampler对象是在训练集分支里创建的，验证集分支拿到的sampler是None。这时候shuffle=False、sampler=None，不报错，但验证集的数据顺序变得很奇怪——因为代码逻辑混乱，验证集的DataLoader实际上还是用了训练集的采样器。
这个坑其实不是ValueError本身，而是“不报错但逻辑错误”的隐藏坑。排查方式只有一种：仔细检查DataLoader的每一个参数最终被赋了什么值。
第二个坑：DistributedSampler和shuffle的级联问题
分布式训练时，每个进程都需要一个DistributedSampler来保证数据不重叠。我一开始写了：
sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank) train_loader = DataLoader(dataset, batch_size=32, shuffle=True, sampler=sampler)报错，然后把shuffle=True删了，继续跑。结果每个epoch开始之前，我忘了调用sampler.set_epoch(epoch)，导致每个epoch的数据划分和顺序完全一样。模型训练出来的效果差得离谱，但没有任何报错。
这个坑告诉我：删掉shuffle=True之后，你得确认你的sampler是否需要在每个epoch开始时被重新初始化或设置epoch。DistributedSampler要求你显式调用set_epoch()，否则永远只有第一轮的随机状态。
第三个坑：sampler和batch_sampler同时用
DataLoader里除了sampler，还有一个batch_sampler参数。如果传了batch_sampler，那么batch_size、shuffle、sampler、drop_last这些参数都不能再设置。有一次我为了自定义batch的组成，写了一个BatchSampler，结果忘了删掉原来的shuffle=True，报错信息变成了：
ValueError: batch_sampler option is mutually exclusive with batch_size, shuffle, sampler, and drop_last虽然报错内容不同，但排查思路是一样的：检查参数之间的互斥关系。
5.3 一个通用的规避技巧
如果你实在不想动现有的代码逻辑，也有一个取巧的办法：自己写一个包装类，让shuffle=True和sampler共存。具体做法是，在传给DataLoader之前，把自定义sampler转换成batch_sampler，因为batch_sampler和shuffle并不直接互斥（实际上交互方式也不太一样）：
from torch.utils.data import DataLoader, BatchSampler # 自定义batch_sampler class MyBatchSampler(BatchSampler): def __init__(self, sampler, batch_size, drop_last, shuffle_within_batch=True): super().__init__(sampler, batch_size, drop_last) self.shuffle_within_batch = shuffle_within_batch def __iter__(self): for batch_indices in super().__iter__(): if self.shuffle_within_batch: yield [batch_indices[i] for i in torch.randperm(len(batch_indices)).tolist()] else: yield batch_indices然后这样使用：
base_sampler = WeightedRandomSampler(weights, num_samples=len(dataset), replacement=True) batch_sampler = MyBatchSampler(base_sampler, batch_size=32, drop_last=False) train_loader = DataLoader(dataset, batch_sampler=batch_sampler)这样就没有shuffle=True了，但通过batch_sampler内部实现了batch内打乱。这样做的好处是灵活，坏处是代码可读性变差，而且需要你对BatchSampler的机制有足够的理解。我个人不太建议在业务代码里这么写，除非你的需求真的很特殊。
6. 不同业务场景下的推荐配置
不同场景对数据采样的需求差异很大，这里给出几组我实际用过的推荐配置，可以直接抄作业。
6.1 常规分类任务
数据分布均匀，没有特殊要求，直接用shuffle=True最省事：
train_loader = DataLoader( train_dataset, batch_size=64, shuffle=True, num_workers=4, pin_memory=True, drop_last=True, )drop_last=True可以避免最后一个batch过小带来的梯度抖动，特别是当数据集大小不能被batch_size整除时，这个参数会让每个epoch的batch数量更一致。代价是会丢掉最后几个样本，如果数据集本身很小，建议改成False。
6.2 类别不平衡任务
类别分布差异大时，用WeightedRandomSampler做有放回采样：
from torch.utils.data import WeightedRandomSampler class_counts = torch.bincount(torch.tensor(labels)) class_weights = 1.0 / class_counts.float() sample_weights = class_weights[labels] sampler = WeightedRandomSampler( weights=sample_weights, num_samples=len(sample_weights), replacement=True ) train_loader = DataLoader( train_dataset, batch_size=64, sampler=sampler, num_workers=4, pin_memory=True, )注意这里没有shuffle=True，因为WeightedRandomSampler本身就是随机采样。如果你想控制每个epoch采样的样本总量，可以调整num_samples参数。比如数据集有10000个样本，但你想让每个epoch只采5000个，就把num_samples设为5000。
6.3 分布式训练
多卡训练时，用DistributedSampler：
from torch.utils.data.distributed import DistributedSampler train_sampler = DistributedSampler( train_dataset, num_replicas=world_size, rank=rank, shuffle=True, # DistributedSampler自身支持shuffle ) train_loader = DataLoader( train_dataset, batch_size=64, sampler=train_sampler, num_workers=4, pin_memory=True, ) # 每个epoch开始前必须调用： # train_sampler.set_epoch(epoch)注意这里DistributedSampler自己有一个shuffle参数，这是采样器内部的属性，跟DataLoader的shuffle参数是两回事，别搞混了。DataLoader的shuffle保持默认False即可，不要再传shuffle=True。
6.4 验证集与测试集
验证集和测试集通常不需要打乱顺序，保持原始顺序有助于复现结果：
val_loader = DataLoader( val_dataset, batch_size=64, shuffle=False, num_workers=4, pin_memory=True, )如果你想根据某种规则筛选验证集样本（比如只验证特定类别的样本），可以用Subset或SubsetRandomSampler：
from torch.utils.data import Subset val_indices = [i for i, label in enumerate(labels) if label == 0] val_subset = Subset(val_dataset, val_indices) val_loader = DataLoader(val_subset, batch_size=64, shuffle=False)7. 从报错出发，理解PyTorch参数设计的哲学
讲完了具体的解决方法和场景配置，最后想聊聊我从这个报错里领悟到的东西。
sampler option is mutually exclusive with shuffle这个报错，表面上看只是个参数冲突提示，但它的背后是PyTorch对“职责单一”原则的坚持。DataLoader把“如何取样本”这件事抽象成了Sampler，shuffle只是RandomSampler的一个便捷入口。如果你需要更复杂的采样逻辑，应该通过Sampler来实现，而不是依赖shuffle这个简单开关。
理解了这一点，很多相关问题都能迎刃而解：
- 为什么
iter(DataLoader)每次返回的batch顺序不同？因为默认的RandomSampler每次迭代都重新生成随机索引。 - 为什么分布式训练要手动调用
set_epoch？因为DistributedSampler需要知道当前是第几个epoch，才能重新划分数据。 - 为什么
shuffle=True时多卡训练会出问题？因为多卡场景下你需要的是DistributedSampler，而不是每个进程各自打乱。
另外，我还想强调一下调试习惯。遇到这类“互斥”报错，我的处理顺序是：第一步，读完整报错信息，包括堆栈；第二步，去源码里找参数校验的逻辑（通常就在DataLoader.__init__的开头几十行）；第三步，根据校验逻辑反推代码里哪些参数组合是矛盾的。这套流程走下来，大部分参数类报错都能在十分钟内定位。
如果你在排查时发现报错信息不够直观，可以自己写个小的测试脚本，打印所有传给DataLoader的参数：
print("shuffle:", shuffle) print("sampler:", sampler) print("batch_sampler:", batch_sampler)有时候问题就是这么简单：你以为sampler是None，实际上它是某个库自动注入的DistributedSampler。
8. 写在最后：别怕报错，怕的是不看报错
这个ValueError报错，几乎每个用过PyTorch的人都遇到过。它不可怕，可怕的是遇到之后不思考，直接删掉某个参数让程序跑起来，然后带着隐患继续往下走。
我个人在实际操作中的体会是：真正让项目出问题的，往往不是这种显式的ValueError，而是那些“能跑但结果是错的”隐藏矛盾。比如shuffle和sampler看起来只报一个错，但你随手把shuffle=True删掉之后，如果没意识到WeightedRandomSampler已经在做随机采样，可能还好；但如果你的sampler是自定义的固定顺序采样器，删掉shuffle之后每一轮epoch的数据顺序都一样，模型训练就会出现莫名其妙的震荡或者收敛变慢。
所以说，遇到任何报错，都别急着“修”，先花两分钟想想报错为什么存在。理解了设计者的意图，你才能真正用好这个框架。
最后再分享一个小技巧：如果你经常写训练代码，建议把这个函数放进你自己的工具库：
def make_loader(dataset, batch_size, shuffle=False, sampler=None, **kwargs): if shuffle and sampler is not None: raise ValueError( "shuffle and sampler cannot be enabled simultaneously; " "if using a custom sampler, set shuffle=False and " "make sure the sampler handles randomness internally." ) return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle, sampler=sampler, **kwargs)以后所有项目都统一走这个入口，这个ValueError基本就再也不会出现在你的训练日志里了。
