异常教程

Python3 os.listdir() 方法（建议收藏）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

在 Python 开发中，文件系统操作是许多项目的核心需求，比如批量处理文件、构建自动化脚本或管理日志。而 os.listdir() 方法作为 Python 标准库中最基础且强大的工具之一，能够帮助开发者快速获取指定目录下的文件和子目录列表。对于编程初学者而言，理解并掌握这一方法，是迈向系统化文件管理的第一步；对于中级开发者，深入其细节与扩展用法则能进一步提升代码的健壮性。本文将以循序渐进的方式，结合实例与类比，解析 Python3 os.listdir() 方法的用法与技巧。

基础用法：从“打开文件柜”开始

想象文件系统如同一个巨大的文件柜，每个文件夹都是一个抽屉，而 os.listdir() 就像“打开抽屉并列出其中所有物品”的动作。

示例 1：列出当前目录的内容

import os  

files = os.listdir(".")  
print("当前目录内容：", files)

运行此代码时，os.listdir(".") 会返回一个列表，包含当前目录中的所有文件名和子目录名。例如，若目录中有 data.csv, report.txt 和 images 文件夹，则输出类似 ['data.csv', 'report.txt', 'images']。

相对路径与绝对路径的区别

os.listdir() 的参数 path 可以是相对路径或绝对路径：

  • 相对路径：以当前脚本所在目录为基准（如 . 表示当前目录，../ 表示父目录）。
  • 绝对路径：从系统根目录开始的完整路径（如 /home/user/files）。
parent_files = os.listdir("..")  

absolute_files = os.listdir("/home/user/projects")

参数解析与异常处理：安全操作的“防护网”

参数 path 的注意事项

若未指定 path，默认会列出当前工作目录。但需要注意：

  1. 路径不存在时：会抛出 FileNotFoundError。
  2. 权限不足时：可能引发 PermissionError。

异常处理：用 try-except 捕获错误

import os  

try:  
    files = os.listdir("/path/that/does/not/exist")  
except FileNotFoundError:  
    print("路径不存在，请检查输入！")  
except PermissionError:  
    print("没有权限访问该目录！")

进阶技巧：从“列出”到“筛选”

仅获取文件列表或目录列表，需结合 os.path 模块的函数进行过滤。

示例 2：区分文件与目录

import os  

current_dir = os.getcwd()  
items = os.listdir(current_dir)  

files = []  
directories = []  

for item in items:  
    item_path = os.path.join(current_dir, item)  
    if os.path.isfile(item_path):  
        files.append(item)  
    elif os.path.isdir(item_path):  
        directories.append(item)  

print("文件：", files)  
print("目录：", directories)

表格对比：常用文件操作函数

函数作用
os.path.isfile(path)判断路径是否为普通文件
os.path.isdir(path)判断路径是否为目录
os.path.exists(path)检查路径是否存在

实际应用场景：自动化脚本的“核心工具”

案例 1：统计指定目录下的图片文件数量

import os  

def count_images(directory):  
    image_extensions = (".jpg", ".jpeg", ".png", ".gif")  
    count = 0  

    for filename in os.listdir(directory):  
        if filename.lower().endswith(image_extensions):  
            count += 1  

    return count  

image_count = count_images("/path/to/images")  
print(f"共有 {image_count} 张图片。")

案例 2：递归遍历多级目录

import os  

def list_all_files(root_dir):  
    for entry in os.listdir(root_dir):  
        entry_path = os.path.join(root_dir, entry)  
        if os.path.isdir(entry_path):  
            list_all_files(entry_path)  # 递归子目录  
        else:  
            print(entry_path)  

list_all_files(".")

注意事项：避坑指南

1. 隐藏文件的处理

在 Unix 系统中，以 . 开头的文件（如 .gitignore）会被视为隐藏文件。若需包含这些文件，需主动检查名称：

hidden_files = [f for f in os.listdir(".") if f.startswith(".")]

2. 跨平台差异

Windows 系统路径使用反斜杠 \，而 Linux/macOS 使用正斜杠 /。建议通过 os.path.join() 构造路径，避免兼容性问题。

3. 性能优化

若需处理大量文件，可结合 os.scandir()（Python 3.5+），它比 os.listdir() 更高效，且能直接获取文件属性：

with os.scandir(".") as entries:  
    for entry in entries:  
        print(entry.name, entry.is_file())  # 直接判断是否为文件

结论

Python3 os.listdir() 方法是开发者与文件系统交互的基础工具，其简洁性与灵活性使其成为自动化任务的“瑞士军刀”。通过本文的讲解，读者应能掌握从基础列表获取到高级过滤与错误处理的全流程，并能结合实际需求设计出健壮的文件管理脚本。

对于希望进一步深入的开发者，可探索 pathlib 模块（Python 3.4+），它以面向对象的方式提供了更优雅的路径操作接口。例如，用 Path 对象替代传统字符串路径，代码可读性将大幅提升：

from pathlib import Path  

for file in Path("/path/to/dir").iterdir():  
    print(file.name)

掌握 os.listdir() 的核心逻辑后，结合其他模块与工具，开发者便能构建出高效、可靠的文件处理系统。

最新发布

查看更多文章