整理项目资料时有时需要把一个文件夹中的文件列成清单方便核对和交接。手动逐个复制文件名容易漏项可以用 Python 完成这一步。这篇教程做一个小工具读取文件夹第一层的文件导出包含“文件名、扩展名、完整路径”的 CSV。只用 Python 标准库无需安装第三方包。适用范围本地文件夹、第一层文件清单。输出是 CSV 文本文件不是带格式的.xlsx工作簿。本例不遍历子文件夹也不读取文件正文。一、运行后得到什么假设sample_files里有这些内容sample_files/ ├── 会议记录.txt ├── 报价,示例.txt ├── 项目 清单.md └── 子文件夹/ └── 不计入本次清单.txt导出的表格有 3 条数据文件名扩展名完整路径示意会议记录.txt.txtD:\demo\sample_files\会议记录.txt报价,示例.txt.txtD:\demo\sample_files\报价,示例.txt项目 清单.md.mdD:\demo\sample_files\项目 清单.md这里的D:\demo只是路径示意运行时会写入你电脑上的实际路径。子文件夹本身及其中的文件不会出现在结果中。二、准备环境与样例在终端执行python --version本例验证环境是 Windows、Python 3.13.5。若命令无法运行需要先准备好 Python 环境再继续下面的步骤。建立一个练习文件夹把下一节代码保存为file_list.py。在旁边建立sample_files文件夹再按上面的结构新建几个文件。文件内容可以留空因为脚本只读取名称和路径。在资源管理器中显示文件扩展名避免把脚本误保存为file_list.py.txt。三、完整代码List files directly inside a folder and export a new CSV file. import argparse import csv from datetime import datetime from pathlib import Path import sys def display_text(value): # Keep formula-like file names as text when viewed in spreadsheet software. if value.lstrip().startswith((, , -, )): return value return value def export_files(source, output): source source.resolve() output output.resolve() if not source.is_dir(): raise ValueError(输入路径不是文件夹请检查路径。) rows [] for item in sorted(source.iterdir(), keylambda p: p.name.casefold()): if item.is_file() and item.resolve() ! output: rows.append([ display_text(item.name), display_text(item.suffix.lower()), str(item.absolute()), ]) output.parent.mkdir(parentsTrue, exist_okTrue) # x creates a new file and refuses to overwrite an existing file. with output.open(x, encodingutf-8-sig, newline) as stream: writer csv.writer(stream) writer.writerow([文件名, 扩展名, 完整路径]) writer.writerows(rows) return len(rows) def main(): parser argparse.ArgumentParser(description导出文件夹第一层的文件清单) parser.add_argument(source, typePath, help要列出文件的文件夹) parser.add_argument(--output, typePath, help新 CSV 文件的保存路径) args parser.parse_args() default_name file_list_ datetime.now().strftime(%Y%m%d_%H%M%S_%f) .csv output args.output or Path(__file__).resolve().parent / results / default_name try: count export_files(args.source, output) except FileExistsError: print(未导出输出文件已存在请换一个输出文件名。, filesys.stderr) return 1 except (OSError, ValueError) as error: print(未完成导出 str(error), filesys.stderr) return 1 print(已导出 str(count) 个文件。) print(保存位置 str(output.resolve())) return 0 if __name__ __main__: raise SystemExit(main())四、运行方法在保存file_list.py的文件夹打开终端执行python file_list.py sample_files成功后会输出已导出 3 个文件。 保存位置你的练习目录\results\file_list_时间戳.csv上面的保存位置是格式示意实际终端会显示完整路径。默认结果保存在脚本旁边的results文件夹文件名包含运行时间。要读取自己的文件夹把sample_files换成实际路径。路径里有空格时保留双引号python file_list.py D:\项目资料也可以明确指定输出文件python file_list.py sample_files --output results/my_file_list.csv如果my_file_list.csv已存在脚本会提示换一个输出文件名。默认带时间戳的方式更适合重复运行。五、代码里最值得理解的四处1.iterdir()只查看当前这一层source.iterdir()列出输入目录的直接子项再用is_file()选择文件。它不会主动进入子文件夹。相关行为可查阅 Python pathlib 官方文档。2.name和suffix分别取名称与后缀例如会议记录.txt的name是完整文件名suffix是.txt。代码将扩展名统一为小写没有扩展名的文件对应单元格为空。对于backup.tar.gz这里取到的是最后一个后缀.gz。3. CSV 交给csv.writer写入文件名可能包含逗号不能直接用字符串拼接一整行。csv.writer会按 CSV 规则处理分隔符和引号打开输出文件时使用newline遵循 Python csv 官方文档 的用法。本例使用utf-8-sig编码输出带 UTF-8 BOM 的文件。如果表格软件打开后仍然乱码或没有分列可以通过“从文本/CSV 导入”选择 UTF-8 编码和逗号分隔符。不同软件的菜单名称可能不同。4. 输出文件使用x模式这个模式要求创建新文件已有同名文件时会报错。脚本捕获错误后给出提示避免重复执行时覆盖已有结果。代码还会给以、、-、开头的名称加上英文单引号供表格软件按文本处理。这个处理会改变 CSV 中对应的显示文本如果要把清单用于程序间精确交换原始名称需要另行设计导出格式。六、怎样核对结果用上面的练习文件夹运行后检查下面几点表头是否为“文件名、扩展名、完整路径”。数据行是否恰好为 3 行。报价,示例.txt是否完整保留在一个单元格中。中文、空格是否保留。子文件夹中的文件是否没有被列入。本例已通过程序化验证演示文件计数、中文与逗号名称、空文件夹、无效输入路径、同名输出拒绝覆盖以及公式样式名称的文本处理。验证检查了导出内容未在 Excel 或 WPS 界面中逐一验证显示效果。七、常见问题提示“输入路径不是文件夹”检查输入的是文件夹还是某个具体文件。相对路径以当前终端目录为起点不确定时使用文件夹的绝对路径并加双引号。导出数量比预期少本例只处理第一层。放在子文件夹中的文件不会计入。读取期间发生权限错误等情况时应查看终端错误提示。文件只有表头如果输入文件夹没有第一层文件导出结果只有表头是正常行为。输出文件已存在更换--output后的文件名或者省略--output使用默认带时间戳的文件名。需要按文件类型筛选可以在当前代码基础上增加扩展名条件。下一篇计划继续做“按扩展名筛选文件并统计数量”让这份清单更方便核对。小结这个小工具把目录里的文件转换成了一张可核对的清单。先用样例确认结果再换成自己的文件夹分享清单前检查完整路径中是否包含不希望公开的姓名或项目名称。本文代码和文字由 AI 辅助制作并进行了本地程序化验证。代码完整保留在正文中可以直接保存后运行。