《超简单：用 Python 让 Excel 飞起来》读书笔记：3.2.2 列出指定路径下的文件和子文件夹名称：os.listdir(path)

🔥个人主页：杨利杰YJlio

❄️个人专栏：《Sysinternals实战教程》 《Windows PowerShell 实战》 《WINDOWS教程》 《IOS教程》

《微信助手》 《锤子助手》 《Python》 《Kali Linux》

《那些年未解决的Windows疑难杂症》

🌟让复杂的事情更简单，让重复的工作自动化

1. 写在前面：批量处理 Excel 前，先要知道文件夹里有什么

本篇是我阅读《超简单：用 Python 让 Excel 飞起来》时整理的读书笔记，对应书中第 3 章 Python 模块里的3.2.2 列出指定路径下的文件和子文件夹名称：os.listdir(path)。

在 Python 办公自动化里，很多任务并不是只处理一个文件，而是要批量处理一个文件夹里的多个 Excel、CSV 或其他数据文件。比如我想把某个目录下所有.xlsx文件找出来，再统一读取、清洗、汇总、输出结果。这个时候，第一步不是读 Excel，而是先搞清楚：目标文件夹里到底有哪些文件和子文件夹。

os.listdir(path)的作用，就是列出指定目录下的所有文件名和文件夹名。它是后续批量筛选、批量读取、批量改名、批量汇总的入口动作。

这张图展示的是os.listdir(path)的整体作用：从指定目录中读取文件和子文件夹名称，并返回一个名称列表。

从图中可以看出，C:\Temp目录下可能同时存在 Excel 文件、CSV 文件、图片文件夹和输出结果文件夹。os.listdir(path)并不会帮我们区分业务含义，它只是把目录下看到的名称先列出来。后面要不要处理、怎么处理，还需要我们自己继续判断。

所以这一节不要只把它当成一个函数记忆点，而要把它理解成“批量自动化的入口”。只要后面涉及批量处理目录文件，基本都会先用它拿到文件名列表。

这条流程就是本篇文章的主线：先列出目录内容，再拼完整路径，再筛选 Excel 文件，最后进入批量处理流程。

2. os.listdir(path) 是什么

os.listdir(path)是 Python 标准库os模块中的一个函数，用来列出指定目录下的内容。这里的“内容”既包括文件，也包括子文件夹。

最基本的写法如下：

importos items=os.listdir(r"C:\Temp")print(items)

可能得到的输出结果类似这样：

['a.xlsx', 'b.csv', 'images', 'result']

这里有两个点必须先记住。第一，返回值是一个list，也就是列表；第二，列表里的每一项是字符串形式的名称。

它返回的是“目录下有哪些名字”，不是“这些文件应该怎么处理”。比如a.xlsx是 Excel 文件，images是文件夹，但os.listdir()本身不会帮你做业务判断。

如果不传入path，也可以直接写：

importos items=os.listdir()print(items)

这种写法默认列出当前工作目录下的内容。它大致等价于：

importos items=os.listdir(os.getcwd())print(items)

不过在办公自动化脚本里，我不建议长期依赖默认当前目录。因为当前工作目录会受到运行方式影响。你在 PyCharm、VS Code、命令行、计划任务里运行脚本时，当前目录可能不一样。

更稳妥的做法是：明确写出要处理的目录路径。这样脚本放到别的电脑上运行时，也更容易排查路径问题。

folder=r"C:\Temp\data"items=os.listdir(folder)

3. 最容易踩坑的点：返回的是“名称”，不是“完整路径”

这一节是新手最容易踩坑的地方。很多人看到os.listdir(r"C:\Temp")返回了a.xlsx，就以为这个结果可以直接拿去读取文件。实际上不行。

os.listdir(path)返回的是名称，例如：

a.xlsx b.csv images result

它不是完整路径，例如：

C:\Temp\a.xlsx C:\Temp\b.csv C:\Temp\images C:\Temp\result

这张图展示的是listdir()返回“名称”和“完整路径”的区别。

从图中可以看出，左边是os.listdir()返回的结果，只有a.xlsx、b.csv、images、result这些名称；右边才是可以真正用于打开、读取、判断的完整路径。

如果你直接把a.xlsx拿去读取，Python 会尝试在当前工作目录里找这个文件，而不是自动去C:\Temp目录下找。这就是很多人明明文件存在，却仍然报FileNotFoundError的原因。

错误理解大概是这样：

importos folder=r"C:\Temp"items=os.listdir(folder)fornameinitems:print(name)# 这里只是打印名称，并不是完整路径

正确思路是：先拿到名称，再把目录路径和名称拼起来，得到完整路径。

这一步看起来很小，但它决定了后面的读取、判断、改名、复制、移动是否能正常执行。

4. 使用 os.path.join() 拼出完整路径

既然os.listdir()返回的是名称，那下一步就要拼出完整路径。这里不要手动用加号拼字符串，更推荐使用os.path.join()。

基本写法如下：

importos folder=r"C:\Temp"items=os.listdir(folder)fornameinitems:full_path=os.path.join(folder,name)print(full_path)

输出结果可能是：

C:\Temp\a.xlsx C:\Temp\b.csv C:\Temp\images C:\Temp\result

这张图展示的是os.path.join()的路径拼接逻辑：文件夹路径加文件名，得到完整路径。

从图中能看出，folder负责表示目录路径，name负责表示文件名或文件夹名，os.path.join(folder, name)则负责把它们组合成完整路径。

推荐使用os.path.join()，原因是它比手动拼接更稳。不同系统的路径分隔符可能不同，手动写\或/容易出错，而os.path.join()会根据系统规则处理路径拼接。

不推荐这样写：

full_path=folder+"\\"+name

这类写法在简单场景下也许能跑，但维护性差，路径里如果多了或少了分隔符，就容易出问题。

路径处理不要靠“看起来差不多”。办公自动化脚本最怕这种小细节，因为你可能处理的是几十个、几百个文件，一旦路径拼错，后面整个批量流程都会失败。

5. 实战 1：只筛选 Excel 文件

在真实办公自动化里，文件夹里往往不只有 Excel 文件，还可能有 CSV、TXT、图片文件夹、临时文件、输出目录等。如果我们直接遍历全部内容，很容易把不该处理的对象也放进流程里。

所以批量处理前，一般要先筛选目标文件。比如只筛选.xlsx和.xls文件。

importos folder=r"C:\Temp"items=os.listdir(folder)excel_files=[]fornameinitems:ifname.lower().endswith((".xlsx",".xls")):excel_files.append(name)print("Excel 文件：",excel_files)

这段代码里，name.lower()是为了统一大小写，避免文件后缀写成.XLSX时判断失败。endswith((".xlsx", ".xls"))可以一次判断多个后缀。

这张图展示的是通过endswith()筛选 Excel 文件的过程，只保留.xlsx和.xls，排除其他无关对象。

从图中可以看出，目录中虽然同时存在 Excel、CSV、文件夹和文本文件，但真正进入批量处理流程的只有符合后缀规则的 Excel 文件。

筛选文件是批量自动化前的关键一步。如果不筛选，后续读取 Excel 时可能会把文件夹、文本文件或临时文件也拿去处理，脚本就会报错。

在处理 Excel 文件时，还要额外注意一种文件：Excel 打开文件时可能生成以~$开头的临时文件。这类文件通常不应该被脚本处理。

importos folder=r"C:\Temp"excel_files=[]fornameinos.listdir(folder):ifname.startswith("~$"):continueifname.lower().endswith((".xlsx",".xls")):excel_files.append(name)print(excel_files)

推荐在批量处理 Excel 时顺手过滤~$临时文件。这个细节很实用，尤其是在用户文件夹或共享目录里处理表格时，经常能避开一些莫名其妙的读取失败。

6. 实战 2：区分文件和文件夹

os.listdir()只返回名称，不告诉你这个名称对应的是文件还是文件夹。如果要区分类型，需要配合os.path.isfile()和os.path.isdir()。

示例代码如下：

importos folder=r"C:\Temp"fornameinos.listdir(folder):full_path=os.path.join(folder,name)ifos.path.isdir(full_path):print("文件夹：",name)elifos.path.isfile(full_path):print("文件：",name)

这里一定要注意，os.path.isfile()和os.path.isdir()判断时，建议传入完整路径，而不是只传文件名。

如果只传name，Python 仍然会基于当前工作目录去判断，而不是基于你原本指定的folder。这和前面“名称不是完整路径”的坑是同一个问题。

这种判断在实际工作中很常用。比如你只想处理文件，不想进入子文件夹，就可以这样写：

importos folder=r"C:\Temp"fornameinos.listdir(folder):full_path=os.path.join(folder,name)ifnotos.path.isfile(full_path):continueprint("准备处理文件：",full_path)

先判断类型，再执行处理，是批量脚本里非常稳的写法。不要假设目录下全是你想要的文件，真实办公目录通常很杂。

7. 实战 3：批量读取 Excel 并输出到 result 文件夹

前面讲了os.listdir()、完整路径拼接、Excel 后缀筛选和文件类型判断。把这些组合起来，就可以形成一个非常常见的批量处理框架。

这里先不展开pandas或xlwings的读写细节，只看批量处理的目录框架。

importos src_dir=r"C:\Temp\data"out_dir=os.path.join(src_dir,"result")ifnotos.path.exists(out_dir):os.makedirs(out_dir)fornameinos.listdir(src_dir):ifname.startswith("~$"):continueifnotname.lower().endswith(".xlsx"):continuesrc_file=os.path.join(src_dir,name)out_file=os.path.join(out_dir,"处理后_"+name)print("处理：",src_file)print("输出：",out_file)# TODO：这里写 Excel 处理逻辑

这段代码的核心逻辑是：先指定输入目录data，再创建输出目录result，然后遍历输入目录中的文件，只处理符合条件的 Excel 文件，最后把处理结果输出到result目录。

这张图展示的是批量处理 Excel 文件并输出到result文件夹的完整流程。

从图中可以看出，批量自动化并不是直接“打开所有文件”，而是有一条清晰链路：读取目录 → 筛选文件 → 执行处理 → 输出结果。

这类框架非常适合后续扩展。今天你可以在TODO位置写 Excel 数据清洗逻辑，明天也可以改成批量改名、批量统计、批量转换格式，甚至批量生成汇总报表。

我的建议是：后续做批量处理时，尽量把输入目录和输出目录分开。不要直接覆盖原文件，尤其是处理财务表、资产表、人事表这类数据时，保留原始数据非常重要。

8. 常见报错与排查思路

os.listdir(path)本身并不复杂，但路径和权限问题很容易让新手卡住。这里我整理几个常见问题。

8.1 FileNotFoundError：路径不存在

如果路径写错，常见报错是FileNotFoundError。比如目录不存在、盘符写错、路径中反斜杠被转义，都可能导致这个问题。

推荐使用原始字符串写 Windows 路径：

folder=r"C:\Temp\data"

不要随手写成"C:\Temp\data"，因为反斜杠可能触发转义。虽然不是每个路径都会出问题，但养成r"..."的习惯更稳。

8.2 PermissionError：没有访问权限

如果访问系统目录、受控共享目录或没有权限的路径，可能会遇到PermissionError。

排查时可以先换一个自己有权限的目录测试，比如C:\Temp。如果普通目录正常，而目标目录失败，就要检查共享权限、NTFS 权限或是否需要管理员权限。

建议先用简单目录跑通代码，再迁移到真实办公目录。这样可以区分是代码问题，还是环境权限问题。

8.3 路径正确，但处理文件时报错

这种情况通常不是os.listdir()本身的问题，而是后续处理环节的问题，比如文件被占用、Excel 临时文件被误处理、文件格式不匹配、扩展名伪装等。

这时可以先打印完整路径确认：

fornameinos.listdir(folder):full_path=os.path.join(folder,name)print(full_path)

先确认脚本到底准备处理哪些文件，再去看后续读取逻辑。不要一报错就怀疑库安装问题，路径和文件对象才是第一证据。

9. 我的总结：listdir 是批量自动化的第一块积木

这一节我最后记住的，不是单纯的os.listdir(path)语法，而是它在办公自动化流程里的位置。

os.listdir(path)负责告诉我们：目标目录下有哪些文件和子文件夹。但它只返回名称，不返回完整路径，也不判断文件类型，更不会自动筛选 Excel 文件。后续必须结合os.path.join()、endswith()、os.path.isfile()、os.path.isdir()才能组成稳定的批量处理流程。

本篇最核心的几个结论是：

第一，os.listdir(path)返回的是名称列表，不是完整路径。

第二，真正操作文件前，要使用os.path.join()拼出完整路径。

第三，批量处理 Excel 前，要先筛选后缀、过滤临时文件、判断文件类型。

如果把这几个动作练熟，后续写批量改名、批量读取、批量汇总、批量输出脚本时，就不会再被“目录遍历”这种基础问题卡住。

对我来说，这一节真正有价值的地方，是让我把“文件夹里有什么”这件小事，放进了完整的 Excel 自动化流程里理解。只有先知道要处理哪些文件，后面的读取、清洗、汇总和输出才有稳定基础。

🔝 返回顶部

点击回到顶部