在使用 Python 处理批量文件时经常会遇到这样一个需求手上有两个文件夹来源可能是旧电脑备份、新电脑资料、项目同步目录或者多个人交替维护后的产物现在想知道两个文件夹中有哪些文件名是重复的。这里的“重复”只针对文件名本身不比较文件内容是否相同也不比较文件大小和修改时间。这类场景在照片整理、日志归档、前端静态资源同步、项目目录比对中非常常见。如果你正在手动打开两个窗口来回翻目录那效率太低了。本文会从最简单的思路开始一步步实现一个可复用的“按文件名对比文件夹”工具并给出 Python、PowerShell、Java 三种实现方式方便你在不同环境下直接选用。1. 需求背景与核心概念1.1 为什么要按文件名对比文件夹先来看两个真实场景。场景一你从旧电脑导出了大量照片部分照片可能已经在新电脑的图库里存在。照片数量动辄几千张内容对不对不好判断但如果你只想知道“这两个文件夹里有没有同名文件”按文件名对比就是最快的筛选方式。场景二你维护一个 Web 项目线上打包产物放在dist_old新构建结果放在dist_new。你想确认新旧版本里哪些文件名没变比如 hash 未变的静态资源通过文件名对比就能快速列出交集再决定是否做增量发布。这两个场景的共同点是只需要文件名不需要马上读取文件内容。按文件名对比的优点是速度快、资源占用低因为只走目录遍历完全不需要计算哈希或读取大文件。1.2 按文件名对比和按内容对比的区别很多人容易把“文件重复”理解成内容相同但实际需求分三种对比维度判断依据速度误判风险只看文件名文件名是否相同最快同名不同内容会被误判文件名 大小文件名与字节大小都相同较快同名同大小但内容不同会被误判内容哈希对文件计算 MD5/SHA 值慢基本不会误判如果目标是“找完全重复的文件并清理磁盘”建议使用内容哈希。但如果目标只是“找出同名项目、核对文件是否缺漏”只看文件名完全够用而且效率高一个数量级。1.3 需要提前明确的两个设计问题在写代码之前有两个问题必须先想清楚否则后续实现容易返工。第一个问题重复文件名是指“两个文件夹根目录下的文件名一致”还是“连子目录路径一起参与比较”。例如A\images\banner.png和B\banner.png如果只看文件名它们是重复的如果把相对路径也纳入比较它们不算重复。本文以“只看文件名”为主同时会补充相对路径模式。第二个问题文件名比较是否区分大小写。Windows 文件系统不区分大小写Linux 严格区分大小写。如果你的脚本要跨平台使用建议提供一个开关默认使用当前系统行为但允许手动指定。2. 环境准备与方案选型2.1 运行环境本文示例的 Python 代码运行在以下环境Python 3.8 及以上版本标准库即可无第三方依赖操作系统Windows / macOS / Linux 均可不需要安装额外工具示例中以 “D:/folder_a” 和 “D:/folder_b” 作为对比目录你可以替换成实际路径。如果使用中文目录名建议在脚本中显式处理编码避免控制台输出乱码。2.2 Python 为什么适合这个任务Python 标准库的os.listdir()和os.walk()可以分别处理单层目录和递归目录没有第三方依赖。再加上argparse标准模块可以把脚本封装成命令行小工具以后每次使用只需要一条命令。2.3 其他备选方案PowerShell适合 Windows 用户不需要安装任何环境打开 PowerShell 直接执行。Java适合已经熟悉 Java IO 的开发人员尤其在跨平台部署给其他同事使用时。批处理/bat也可以实现但处理中文路径和输出编码时比较麻烦不建议首选。下面会重点讲 Python 实现因为它是综合体验最好的方案然后补充 PowerShell 和 Java 的核心逻辑。3. 核心实现思路拆解不管是哪种语言按文件名对比文件夹的核心流程都只有三步遍历文件夹得到所有文件名。对文件名列表去重得到这个文件夹的“文件名集合”。求两个集合的交集交集就是重复文件名。用集合而不是列表来存储文件名是这一步的关键优化。如果使用列表判断一个文件名是否在另一个列表中需要遍历整个列表时间复杂度是 O(n×m)使用集合后查找时间复杂度降到 O(1)总复杂度仅为 O(nm)。文件数量越大性能差距越明显。3.1 如何表示一个文件名最简单的方式是只取文件名本身也就是os.path.basename()的返回值。例如D:/folder_a/2024/photo/IMG_001.jpg只取文件名就是IMG_001.jpg如果两个文件夹中恰好都有IMG_001.jpg则认为重复。3.2 如何处理子目录处理子目录有两种策略策略一只处理两个文件夹的顶层文件忽略子目录。策略二递归遍历全部子目录把文件名取出来比较。大多数实际需求都是后者因为文件通常分层存放。本文的 Python 示例默认采用递归遍历同时保留一个--no-recursive开关。3.3 相对路径模式扩展如果需要目录结构也参与比较可以把文件夹名 分隔符 文件名作为比较键。举例folder_a/images/banner.png folder_b/images/banner.png两者相对路径一致判定为重复。而folder_a/images/banner.png folder_b/banner.png两个键分别是images/banner.png和banner.png不会判定为重复。这个模式适合“目录结构必须完全一致”的场景。4. Python 完整实战4.1 创建项目结构为了便于后续扩展建议建立一个独立目录存放脚本compare_files/ └── compare_filenames.py整个项目只需要这一个 Python 文件不需要配置文件。4.2 基础版本快速实现先看最简单的基础版本这个版本只对比两个文件夹顶层文件的文件名适合临时使用便于理解核心逻辑。# 文件路径compare_filenames.py import os def get_files_by_name(folder): 获取文件夹中所有文件名返回文件名集合 try: names os.listdir(folder) except FileNotFoundError: print(f错误文件夹不存在 - {folder}) return set() except PermissionError: print(f错误没有权限访问 - {folder}) return set() return {name for name in names if os.path.isfile(os.path.join(folder, name))} def find_duplicate_names(folder1, folder2): 对比两个文件夹返回重复文件名 files1 get_files_by_name(folder1) files2 get_files_by_name(folder2) return files1 files2 if __name__ __main__: f1 input(请输入第一个文件夹路径).strip().strip() f2 input(请输入第二个文件夹路径).strip().strip() duplicates find_duplicate_names(f1, f2) if duplicates: print(f\n找到 {len(duplicates)} 个重复文件名) for name in sorted(duplicates): print(f - {name}) else: print(\n没有找到重复文件名。)代码解释os.listdir(folder)返回文件夹下的所有条目包括文件和子目录。列表推导式中的os.path.isfile()用来过滤掉子目录只保留文件。files1 files2是 Python 集合的交集运算结果就是两边都存在的文件名。考虑到你可能会从资源管理器复制路径路径中可能包含引号所以加上了.strip()。运行方式python compare_filenames.py预期输出示例请输入第一个文件夹路径D:/folder_a 请输入第二个文件夹路径D:/folder_b 找到 2 个重复文件名 - IMG_001.jpg - report.docx这个基础版本已经能解决小目录的临时对比需求但它不处理子目录也不支持大小写开关。如果想要更实用需要进阶版本。4.3 进阶版本支持递归、大小写、输出文件进阶版本使用argparse解析命令行参数加入递归遍历、忽略大小写、输出结果到文件等能力。# 文件路径compare_filenames.py import os import argparse import sys def walk_files(folder, ignore_caseFalse): 递归遍历文件夹返回 {比较键: 完整路径} 字典。 如果 ignore_case 为 True比较键统一转为小写。 result {} for root, dirs, files in os.walk(folder): for filename in files: full_path os.path.join(root, filename) key filename.lower() if ignore_case else filename result.setdefault(key, []).append(full_path) return result def compare_folders(folder1, folder2, ignore_caseFalse, keep_relativeFalse): 对比两个文件夹。 keep_relativeFalse只看文件名本身。 keep_relativeTrue比较相对路径目录结构也要一致。 files1 {} files2 {} if keep_relative: for root, dirs, files in os.walk(folder1): for f in files: full_path os.path.join(root, f) rel_path os.path.relpath(full_path, folder1) key rel_path.lower() if ignore_case else rel_path files1.setdefault(key, []).append(full_path) for root, dirs, files in os.walk(folder2): for f in files: full_path os.path.join(root, f) rel_path os.path.relpath(full_path, folder2) key rel_path.lower() if ignore_case else rel_path files2.setdefault(key, []).append(full_path) else: files1 walk_files(folder1, ignore_case) files2 walk_files(folder2, ignore_case) duplicate_keys set(files1.keys()) set(files2.keys()) return duplicate_keys, files1, files2 def main(): parser argparse.ArgumentParser( description对比两个文件夹中的文件找出重复文件名只对比文件名不比较文件内容 ) parser.add_argument(folder1, help第一个文件夹路径) parser.add_argument(folder2, help第二个文件夹路径) parser.add_argument( --ignore-case, actionstore_true, help忽略文件名大小写Windows 下建议开启, ) parser.add_argument( --keep-relative, actionstore_true, help比较相对路径而不是纯文件名目录结构不一致则不算重复, ) parser.add_argument( --output, -o, help将对比结果输出到指定文本文件, ) args parser.parse_args() if not os.path.isdir(args.folder1): print(f错误第一个文件夹不存在或不可访问 - {args.folder1}, filesys.stderr) sys.exit(1) if not os.path.isdir(args.folder2): print(f错误第二个文件夹不存在或不可访问 - {args.folder2}, filesys.stderr) sys.exit(1) duplicate_keys, files1, files2 compare_folders( args.folder1, args.folder2, ignore_caseargs.ignore_case, keep_relativeargs.keep_relative, ) lines [] if duplicate_keys: lines.append(f找到 {len(duplicate_keys)} 个重复文件名\n) for key in sorted(duplicate_keys): lines.append(f 文件名{key}) lines.append(f 所在位置1{files1[key][0]}) lines.append(f 所在位置2{files2[key][0]}) else: lines.append(没有找到重复文件名。) output_text \n.join(lines) print(output_text) if args.output: try: with open(args.output, w, encodingutf-8) as f: f.write(output_text \n) print(f\n结果已保存到{args.output}) except OSError as e: print(f警告结果写入文件失败 - {e}, filesys.stderr) if __name__ __main__: main()代码解释argparse负责接收命令行参数让脚本不再是输入式交互更便于自动化调用。walk_files()返回字典键是文件名值是完整路径列表。同一个文件夹里也可能存在同名文件在不同子目录所以用setdefault(key, []).append()保存所有路径。keep_relativeTrue时使用os.path.relpath()计算相对路径目录树不一致就不会判重。输出到文件时使用encodingutf-8避免 Windows 下默认 GBK 编码导致写中文乱码。运行方式python compare_filenames.py D:/folder_a D:/folder_b # 忽略大小写 python compare_filenames.py D:/folder_a D:/folder_b --ignore-case # 比较相对路径 python compare_filenames.py D:/folder_a D:/folder_b --keep-relative # 结果输出到文件 python compare_filenames.py D:/folder_a D:/folder_b -o result.txt4.4 运行验证为了验证效果准备两个测试目录D:/folder_a/ ├── IMG_001.jpg ├── report.docx ├── notes.txt └── images/ └── banner.png D:/folder_b/ ├── IMG_001.jpg ├── report.docx ├── old_data.xlsx └── images/ └── banner.png执行python compare_filenames.py D:/folder_a D:/folder_b输出找到 3 个重复文件名 文件名IMG_001.jpg 所在位置1D:/folder_a/IMG_001.jpg 所在位置2D:/folder_b/IMG_001.jpg 文件名banner.png 所在位置1D:/folder_a/images/banner.png 所在位置2D:/folder_b/images/banner.png 文件名report.docx 所在位置1D:/folder_a/report.docx 所在位置2D:/folder_b/report.docx可以看到即使在folder_a中banner.png位于images子目录只要文件名相同也会被识别为重复符合“只对比文件名”的初始需求。5. 其他实现方式5.1 PowerShell 实现如果只是在 Windows 上做一次性检查不需要引入 PythonPowerShell 一句脚本就能完成。# 定义两个文件夹路径 $folder1 D:\folder_a $folder2 D:\folder_b # 递归获取所有文件名 $files1 Get-ChildItem -Path $folder1 -File -Recurse | Select-Object -ExpandProperty Name $files2 Get-ChildItem -Path $folder2 -File -Recurse | Select-Object -ExpandProperty Name # 求交集 $duplicates $files1 | Where-Object { $_ -in $files2 } if ($duplicates) { Write-Host 找到 $($duplicates.Count) 个重复文件名 -ForegroundColor Green $duplicates | Sort-Object -Unique | ForEach-Object { Write-Host - $_ } } else { Write-Host 没有找到重复文件名。 }注意-File参数只在 PowerShell 3.0 之后可用它表示只列举文件不包含文件夹。Sort-Object -Unique去掉重复项因为递归得到的文件名列表可能包含重复子目录中的同名文件。5.2 Java 实现核心逻辑在 Java 中可以使用Files.walk()遍历目录然后同样用集合求交集。import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.Set; import java.util.stream.Collectors; import java.util.stream.Stream; public class CompareFolders { public static void main(String[] args) throws IOException { String folder1 D:/folder_a; String folder2 D:/folder_b; SetString files1 listFileNames(folder1); SetString files2 listFileNames(folder2); files1.retainAll(files2); if (files1.isEmpty()) { System.out.println(没有找到重复文件名。); } else { System.out.println(找到 files1.size() 个重复文件名); files1.stream().sorted().forEach(name - System.out.println( - name)); } } private static SetString listFileNames(String folder) throws IOException { try (StreamPath stream Files.walk(Paths.get(folder))) { return stream .filter(Files::isRegularFile) .map(path - path.getFileName().toString()) .collect(Collectors.toSet()); } } }核心逻辑同样是三步递归遍历、提取文件名、集合取交集。这段代码依赖 Java 8 及以上版本。5.3 为什么不建议直接用文件去重工具有读者可能会问市面上有 fdupes、dupeGuru 这类专门找重复文件的工具为什么还要自己写脚本这是因为这些工具默认按文件内容哈希找重复需要读取每个文件的全部字节。如果两个文件夹里文件很多、体积很大做内容哈希会非常慢。而且很多重复文件清理工具带有删除功能误操作风险更高。单纯对比文件名自己写几行脚本更轻量、更可控也方便和 CI 流程集成。6. 常见问题与排查思路6.1 中文文件名乱码在 Windows 命令行中运行 Python 脚本如果输出中文文件名出现乱码通常是控制台编码问题。解决方式代码中输出结果时统一用 UTF-8 编码。如果使用--output参数把结果写到文件再用支持 UTF-8 的编辑器打开。6.2 遍历大目录非常慢如果文件夹里文件数量达到几十万os.walk()和set依然能正常工作但首次遍历不可避免要读取目录信息。此时可以换用 Windows 下的dir /s /b命令辅助生成文件列表再用 Python 对比列表文件能够明显提升体验dir /s /b D:\folder_a list_a.txt dir /s /b D:\folder_b list_b.txt然后对两个列表文件做对比即可。6.3 提示没有权限访问文件夹在 Linux 或 macOS 下如果目标文件夹权限不足会遇到权限报错。建议先用系统命令确认权限ls -l /path/to/folder然后使用chmod或切换对应用户。生产环境里不要轻易用 root/sudo 运行脚本尽量使用有最小权限的账号。6.4 符号链接导致死循环os.walk()默认不会递归进入符号链接指向的目录所以基本不用担心死循环。但如果你改了代码主动进入符号链接目录就要注意记录已经访问过的真实路径避免 A 链接到 B、B 又链接到 A 的情况。6.5 同名但大小写不同Linux 下A.TXT和a.txt是两个文件Windows 下则是同一个文件。如果你的脚本要同时运行在不同平台建议在命令行参数中显式指定是否忽略大小写而不是依赖默认值。进阶版脚本已经提供--ignore-case开关可以满足这个需求。7. 最佳实践与工程建议7.1 默认只读不要直接删除文件名对比脚本应该默认只输出报告不做删除、移动、重命名等操作。如果后续确需清理重复文件也建议先导出结果清单人工确认后再执行删除。可以在脚本中加一个--dry-run参数逻辑是“只打印将要操作的路径不真正操作”这是生产环境中最稳妥的做法。7.2 对比结果保存为报告对大目录执行对比时控制台输出容易被刷屏而且事后不好追溯。建议始终使用-o result.txt参数保存结果。报告内容至少包含重复文件名文件在第一个文件夹中的完整路径文件在第二个文件夹中的完整路径7.3 结合文件大小进一步筛选如果只对比文件名误判太多可以在文件名之外再加一个“文件大小”的判断条件。注意这里的文件大小可以通过os.path.getsize()获取不需要读取文件内容速度依然很快。实现时只需要把比较键从“文件名”扩展为“(文件名, 文件大小)”。def get_size_key(folder, ignore_caseFalse): result {} for root, dirs, files in os.walk(folder): for filename in files: full_path os.path.join(root, filename) size os.path.getsize(full_path) name_key filename.lower() if ignore_case else filename key (name_key, size) result.setdefault(key, []).append(full_path) return result这个方法可以在日志场景中快速筛选“文件名和大小都相同”的重复文件过滤掉同名但内容可能不同的文件比内容哈希快很多。7.4 编码统一是协作基础脚本保存、文件输出、控制台三个环节的编码要保持一致。推荐统一使用 UTF-8。如果是在 Windows 老项目中使用可能需要把输出文件的编码调整为 ANSI 以便 Excel 直接打开这时可以在open()时指定encodinggbk但要注意 Linux 环境不支持 GBK 编码时的兼容处理。7.5 用配置文件记录路径如果定期执行同一个对比任务不要每次手动输入路径。可以把两个文件夹路径写在一个配置文件里脚本读取配置执行。例如创建一个简单的config.ini[paths] folder1 D:\data\backup folder2 D:\data\current然后在 Python 中读取import configparser config configparser.ConfigParser() config.read(config.ini, encodingutf-8) folder1 config.get(paths, folder1) folder2 config.get(paths, folder2)这样适合定时任务例如每天凌晨对比两个目录生成报告。7.6 注意路径长度限制Windows 系统默认路径长度限制为 260 个字符文件层级很深时会报错。Python 3.6 之后在 Windows 10 上可以通过\\?\前缀支持长路径但更简单的做法是尽量把对比目标放在磁盘根目录附近或者在系统策略中开启长路径支持。8. 收尾这篇文章从一个高频的文件整理需求出发完整实现了“按文件名对比两个文件夹”的 Python 工具并提供了 PowerShell 和 Java 的参考代码。核心思路可以浓缩为一句话遍历文件夹形成文件名集合再求两个集合的交集。掌握了集合运算这个关键点以后遇到类似的文件对比问题都能快速套用。文中进阶版脚本已经能处理递归目录、大小写忽略、相对路径模式、结果输出等常见场景建议你先在测试目录上跑通再用于真实数据。如果你的目录文件量很大推荐加上文件大小作为辅助判断条件如果还要更精确那就需要走内容哈希路线了。文件名对比只是第一步实际工程中往往要用多种维度逐层筛选才能得到最可靠的结果。希望这个脚本能帮你节省时间。如果你手头有其他文件管理需求也推荐自己试着扩展代码比如加一个“差异文件名输出”的功能说不定下次整理资料时就用上了。