C语言遍历文件夹并按文件名关键字搜索文件

陆遥

发布时间：2026-10-13 | 4人浏览过

原创

在Windows开发环境中，利用标准库函数遍历目录并筛选特定文件是常见需求。本文将展示如何通过C/C++代码实现递归文件夹扫描，并根据关键字精确查找文件名。

环境准备与原理

本方案基于Windows平台，依赖Microsoft C Runtime (MSVCRT)提供的文件系统API。主要涉及以下头文件与函数：

<io.h>：提供 _finddata_t 结构体以及文件搜索相关函数。
<string> 或 <cstring>：用于处理路径拼接和字符串匹配（如 strstr）。
_findfirst / _findnext：执行目录枚举。
_findclose：关闭搜索句柄，防止资源泄漏。

核心实现步骤

第1步：初始化搜索条件与路径格式化

首先定义一个递归函数 filesearch，接收目标目录路径 path 和搜索关键字 mode。在构建搜索通配符之前，需检查路径末尾是否已存在反斜杠 \，若不存在则需补充，以确保生成合法的搜索模式（如 C:\Data\*.*）。

#include <iostream>
#include <string>
#include <io.h>
#include <cstring>
using namespace std;

void filesearch(string path, string mode) {
    // 1. 确保路径结尾没有多余的斜杠
    if (!path.empty() && path[path.size()-1] == '\\') {
        path.resize(path.size()-1);
    }
    // 构建当前目录的通配符搜索字符串
    string curr = path + "\\*.*";
}

第2步：启动首次目录扫描

调用 _findfirst 获取第一个匹配的条目。该函数返回一个长整型句柄（handle），若返回值为 -1L，说明目录为空或不存在，直接返回。同时，获取的文件属性会存储在 _finddata_t 结构体中。

struct _finddata_t filefind;
int done = 0;
long handle;

// 执行首次查找
if ((handle = _findfirst(curr.c_str(), &filefind)) == -1L) {
    return; // 未找到文件或目录错误
}

第3步：循环处理当前层级文件

进入 while 循环，每次调用 _findnext 获取下一个条目。在处理每个条目时需执行以下逻辑：

跳过系统目录：忽略 . 和 .. 目录项。
关键字匹配：使用 strstr(filefind.name, mode.c_str()) 判断文件名是否包含搜索关键字。若匹配，则输出完整路径。
递归子目录：检查 filefind.attrib 是否包含 _A_SUBDIR 标志。如果是目录，则递归调用 filesearch 深入下一层。

第4步：清理资源

当循环结束（即无更多匹配项时），必须调用 _findclose(handle) 释放操作系统分配的搜索句柄，否则可能导致内存或文件描述符泄漏。

完整代码示例

以下是整合上述逻辑的完整可运行代码。注意：在实际工程中，建议使用C++标准库的路径管理工具或Boost.Filesystem以增强跨平台兼容性，此处仅针对Windows原生C++演示。

#include <iostream>
#include <string>
#include <io.h>
#include <cstring>

using namespace std;

void filesearch(string path, string mode) {
    struct _finddata_t filefind;
    
    // 规范化路径，移除末尾的反斜杠
    if (!path.empty() && path.back() == '\\') {
        path.pop_back();
    }
    
    // 构造搜索路径，例如: C:\Folder\*.*
    string searchPattern = path + "\\*.*";
    
    long handle;
    int done = 0;
    
    // 开始搜索
    if ((handle = _findfirst(searchPattern.c_str(), &filefind)) == -1L) {
        return; // 搜索失败或空目录
    }
    
    // 遍历所有匹配项
    while (!(done = _findnext(handle, &filefind))) {
        const char* filename = filefind.name;
        
        // 跳过当前目录(.)和上级目录(..)
        if (strcmp(filename, ".") == 0 || strcmp(filename, "..") == 0) {
            continue;
        }
        
        // 构建完整路径
        string fullPath = path + "\\" + filename;
        
        // 检查文件名是否包含关键字
        if (strstr(filename, mode.c_str()) != nullptr) {
            cout << "找到文件/文件夹: " << fullPath << endl;
        }
        
        // 如果是目录，则递归搜索
        if (filefind.attrib & _A_SUBDIR) {
            filesearch(fullPath, mode);
        }
    }
    
    // 关闭句柄
    _findclose(handle);
}

int main() {
    string path, mode;
    
    cout << "请输入要搜索的目录 (例如 D:\\Test): ";
    cin >> path;
    
    cout << "请输入要匹配的关键字: ";
    cin >> mode;
    
    // 执行搜索
    filesearch(path, mode);
    
    return 0;
}

注意事项与排错

权限问题：如果程序因访问受限目录而返回 -1，请检查是否以管理员身份运行，或尝试更改为有读取权限的目录。
编码问题：_findfirst 在不同Windows版本对非ASCII字符的支持可能不同。若文件名包含中文，建议确认项目源文件编码为UTF-8或GBK（视编译器设置而定），或者使用宽字符版本的函数 _wfindfirst。
性能优化：对于极大数量的文件，递归深度过深可能导致栈溢出。必要时可改为迭代实现的广度优先搜索（BFS）。