用Python按模板批量创建文件夹并保留嵌套结构完整方案

在日常业务开发和项目管理中，有一个看似不起眼却非常浪费精力的重复性工作：每次新建项目、新开模块或新接入一套业务时，都要手工创建一堆层级嵌套的文件夹。更麻烦的是，不同同事建出来的目录结构往往不一致，有人叫 src，有人叫 source，有人把配置文件放在根目录，有人放在 config 下面。一次两次还好，次数多了就会发现，团队协作时经常要互相问“你的配置放哪了”。本文基于“按模板批量创建文件夹并保留结构”这个实际需求，整理一套完整可复用的 Python 脚本方案，带读者从概念、原理到代码落地，一次性解决目录结构混乱和重复手工建文件夹的问题。

这篇文章适合以下几类读者：一是经常需要初始化新项目的后端开发、前端工程师和数据工程师；二是需要在团队内统一项目目录规范的团队负责人；三是对 Python 文件处理、递归遍历感兴趣的学习者。读完本文后，你将掌握如何用 JSON 或文本文件定义目录模板、如何用 Python 递归解析模板并批量创建文件夹、如何保留下级嵌套结构，以及如何在实际工程中规避路径、权限、重复创建等常见坑。

1. 背景与核心概念

1.1 什么是“按模板批量创建文件夹”

先找一个身边的场景来理解。假设你在一个数据团队工作，每条数据接入任务都要建立一个独立的工作目录，里面必须包含 config、input、output、log、scripts 这几个子目录，而 scripts 下又要继续分为 etl 和 check 两个目录。如果每次都手动执行 mkdir -p config input output log scripts/etl scripts/check，不仅容易记漏，而且换一台电脑、换一个同事操作，命名习惯可能就变了。

所谓“按模板批量创建文件夹”，就是预先设计好一套目录结构的模板，然后通过脚本批量创建与之完全相同的目录树。这里的模板既可以是写在 JSON 配置文件里的树形数据，也可以是一段缩进表示的文本目录树。脚本读取模板后，在指定的目标路径下生成对应的文件夹集合，并且完整保留模板中的上下级关系。

1.2 “保留结构”的含义

单独创建一个文件夹并不难，难的是保留结构。假设模板是这样的：

code复制project/
├── docs/
│   ├── design/
│   └── manual/
├── code/
│   ├── core/
│   └── tests/
└── output/

“保留结构”意味着最终生成结果必须与模板完全一致：docs 下必须有 design 和 manual，code 下必须有 core 和 tests，不能出现多一层、少一层，也不能把嵌套目录全部平铺到根目录。这在手工操作时很容易出错，而脚本可以用递归方式保证每一层都被正确处理。

1.3 应用场景

这类工具的使用场景非常广泛，本文列举几个典型场景。

第一个场景是项目初始化。团队统一规定新项目的目录结构后，开发者在项目开始阶段运行一次脚本，就能得到标准目录，避免因为个人习惯产生差异。

第二个场景是按批次创建多套目录。例如一个月内要对接 30 个数据源，每个数据源都要建立独立的接入目录，目录结构相同，只是最外层的项目名称不同。脚本可以循环读取项目名单，逐一生成结构一致的目录树。

第三个场景是数据治理和数据仓库分层建模。数据仓库的 ods、dwd、dws、ads 等分层目录需要保持稳定结构；如果每次新建主题域都重新手动创建，很容易出现分层不完整的情况。

第四个场景是知识管理与文档沉淀。团队知识库需要统一的文档分类结构，用模板生成目录后，成员只需要把文档放进对应目录，查找效率会明显提升。

从这些场景可以看出，批量创建文件夹虽然听起来简单，但只要叠加“模板化”和“保留结构”这两个要求，就很适合用脚本自动化解决。

2. 环境准备与版本说明

本文的完整示例基于 Python 3 实现。Python 3 在 Windows、Linux、macOS 三大平台上都有良好的支持，而且标准库 os 和 pathlib 已经足以完成目录遍历和创建，不需要额外安装第三方库，对于多数环境来说非常友好。

需要说明的是，不同操作系统对路径分隔符的处理方式不同。Windows 使用反斜杠 \，Linux 和 macOS 使用正斜杠 /。为了写出跨平台可用的脚本，本文统一使用 pathlib.Path 处理路径，它可以自动适配当前操作系统的路径分隔规则。

本文示例的软件环境如下：

版本不需要刻意追求最新。pathlib 在 Python 3.4 引入，Python 3.6 以后已经非常稳定，本文使用 Python 3.8 以上语法只是为了代码更简洁，例如 f-string 格式化等特性；如果你的环境是更早的 Python 版本，需要把 f-string 改成 format() 方法。实际开发时请根据本机安装的 Python 版本做适当调整。

项目目录结构建议保持简洁：

code复制folder_template_project/
├── template.json          # 目录结构模板文件
├── create_folders.py      # 核心脚本
└── output/                # 脚本生成的目录（运行时自动创建）

其中 template.json 定义标准目录结构，create_folders.py 负责解析模板并创建目录。你也可以根据项目实际情况调整这些文件的路径和名称。

3. 核心原理拆解

3.1 模板文件的两种常见设计

模板本身可以用多种方式描述，本文重点介绍两种：JSON 嵌套对象和文本目录树。

JSON 嵌套对象是程序化处理最方便的方式，它的基本结构是一个字典，键是文件夹名称，值要么是空对象表示没有子目录，要么是嵌套对象表示子目录。

json复制{
  "project": {
    "docs": {
      "design": {},
      "manual": {}
    },
    "code": {
      "core": {},
      "tests": {}
    },
    "output": {}
  }
}

这段 JSON 表示在目标路径下创建一个名为 project 的根目录，其下有 docs、code、output 三个子目录，其中 docs 下继续包含 design 和 manual，code 下继续包含 core 和 tests。

文本目录树更适合直接阅读，缩进直观展示层级。例如：

code复制project/
  docs/
    design/
    manual/
  code/
    core/
    tests/
  output/

相比 JSON，文本目录树需要额外的解析逻辑，例如根据缩进数量判断层级。本文的实战案例采用 JSON 模板，原因有两个：一是 JSON 本身就是嵌套结构，和目录树天然对应，递归处理非常直接；二是在团队协作中，JSON 文件容易做 diff 审查，哪个目录被删改一目了然。

3.2 递归遍历模板

目录树本质上是树形结构。处理树形结构最自然的做法是递归：函数接收当前路径和当前目录字典，遍历字典的每一项，如果是普通目录名，就创建目录；如果值还是一个嵌套字典，就继续深入递归。

这里的核心逻辑可以用一段伪代码表示：

code复制def create_tree(current_path, tree_dict):
    for name, children in tree_dict.items():
        new_path = current_path / name
        new_path.mkdir(parents=True, exist_ok=True)
        if children:
            create_tree(new_path, children)

关键点有两个。第一，mkdir 方法中的 parents=True 表示如果父目录不存在则自动创建父目录，exist_ok=True 表示目录已存在时不报错；第二，递归出口是 children 为空字典的情况，此时创建完当前目录后直接返回，不再继续向下处理。

3.3 参数化目录名的处理

实际使用模板时，往往不希望目录名完全写死。例如批量创建 10 个数据接入目录，最外层可以是 source_001、source_002，而内层结构完全一致。此时模板中可以定义占位符，用 {project_name} 这样的字符串代表目录名中可变化的部分。

占位符替换的本质是在递归创建之前，先把模板字典中的所有字符串做一次替换。由于字典的键是字符串，替换键名即可实现目录名参数化。Python 中可以通过递归访问字典的键，找到包含占位符的键名并替换为实际值。

需要注意的是，占位符替换一定要在创建之前完成，否则脚本运行时才逐层替换会非常繁琐。可以把“模板解析”和“目录创建”拆成两个阶段：第一阶段递归替换键名，得到一份最终模板；第二阶段按最终模板创建目录。

3.4 冲突与幂等性

批量创建文件夹还有一个工程上很重要的话题：幂等性。所谓幂等，指的是同一个操作执行一次和执行多次，最终结果一致。

如果脚本不是幂等的，第一次运行创建了全部目录，第二次运行却因为某些目录已存在而报错，这个脚本就不适合反复使用。解决思路很简单：创建目录时使用 exist_ok=True，已存在的目录直接跳过。这样既不会抛异常，也不会重复覆盖已有文件，可以安全地反复执行。

对于“保留结构”来说，幂等性还意味着结构只增不减。脚本不应该因为你这次模板里少了某个目录，就删除目标位置已经存在的同名目录。创建目录的职责是“保证结构存在”，而不是“保证结构唯一”。

4. 完整实战案例

4.1 需求描述

接下来实现一个完整的实战项目。假设公司要求每个新项目初始化时必须包含以下目录结构：

code复制{project_name}/
├── config/
├── docs/
│   ├── api/
│   └── meeting/
├── scripts/
│   ├── build/
│   └── deploy/
├── src/
│   └── main/
│       └── java/
├── test/
│   └── cases/
└── output/

现在需要编写一个 Python 脚本，传入项目名称，脚本读取模板，在指定的根目录下批量创建这套结构，并且完整保留嵌套层级。

4.2 定义模板文件

首先在项目目录下创建 template.json，内容定义上述结构。为了让模板更通用，使用 {project_name} 作为占位符。

文件路径：folder_template_project/template.json

json复制{
  "{project_name}": {
    "config": {},
    "docs": {
      "api": {},
      "meeting": {}
    },
    "scripts": {
      "build": {},
      "deploy": {}
    },
    "src": {
      "main": {
        "java": {}
      }
    },
    "test": {
      "cases": {}
    },
    "output": {}
  }
}

文件中的键 {project_name} 会在脚本运行时被替换成实际项目名称。{} 表示当前目录没有下级目录。src 下嵌套 main，main 下嵌套 java，这个三层结构用来验证递归深度是否正确。

4.3 编写核心脚本

接下来编写 create_folders.py。脚本包含四个主要函数：读取模板、递归替换占位符、递归创建目录、主流程控制。

文件路径：folder_template_project/create_folders.py

python复制# -*- coding: utf-8 -*-
"""
按模板批量创建文件夹并保留结构
作者：整理分享
功能：读取 template.json，将 {project_name} 替换为实际项目名，
      在目标根目录下递归创建完整的目录树。
用法：python create_folders.py
"""
import json
import sys
from pathlib import Path


def load_template(template_path):
    """
    读取 JSON 模板文件。

    Args:
        template_path: 模板文件路径，可以是 str 或 Path。

    Returns:
        dict: 解析后的模板字典。

    Raises:
        FileNotFoundError: 模板文件不存在时抛出。
        json.JSONDecodeError: 模板文件不是合法 JSON 时抛出。
    """
    template_path = Path(template_path)
    if not template_path.exists():
        raise FileNotFoundError(f"模板文件不存在: {template_path}")
    with open(template_path, "r", encoding="utf-8") as f:
        return json.load(f)


def replace_placeholders(node, project_name):
    """
    递归替换模板字典中的占位符 {project_name}。

    Args:
        node: 当前节点的字典。
        project_name: 实际项目名称。

    Returns:
        dict: 替换完成后的新字典。
    """
    new_node = {}
    for key, value in node.items():
        new_key = key.replace("{project_name}", project_name)
        if isinstance(value, dict):
            # 如果键对应的值仍然是字典，说明还有子目录，递归处理
            new_node[new_key] = replace_placeholders(value, project_name)
        else:
            # 理论上模板中值应为字典；这里做兜底，保留原值
            new_node[new_key] = value
    return new_node


def create_folders_from_dict(current_path, tree_dict):
    """
    递归创建目录树。

    Args:
        current_path: 当前所在的 Path 对象。
        tree_dict: 模板字典，键为目录名，值为子目录字典。
    """
    for name, children in tree_dict.items():
        new_path = current_path / name
        # 关键点：parents=True 自动创建父目录，exist_ok=True 已存在不报错
        new_path.mkdir(parents=True, exist_ok=True)
        if children:
            create_folders_from_dict(new_path, children)


def generate_projects(project_names, template_path, output_root):
    """
    按项目名称列表批量生成目录结构。

    Args:
        project_names: 项目名称列表。
        template_path: 模板文件路径。
        output_root: 生成的根目录路径。
    """
    template = load_template(template_path)
    output_root = Path(output_root)
    output_root.mkdir(parents=True, exist_ok=True)

    for project_name in project_names:
        project_template = replace_placeholders(template, project_name)
        create_folders_from_dict(output_root, project_template)
        print(f"[OK] 已生成项目目录: {output_root / project_name}")


def main():
    # 你可以手动修改这里，或改成从命令行参数、Excel、文本文件读取
    project_names = ["demo_project", "report_service", "data_sync"]

    template_path = "template.json"
    output_root = "output"

    if not project_names:
        print("项目名单为空，请先配置项目名称。")
        sys.exit(1)

    generate_projects(project_names, template_path, output_root)

    print("全部目录已创建完成，请检查 output 目录。")


if __name__ == "__main__":
    main()

这个脚本有几个值得重点解释的地方。

首先是 load_template 函数。它用 Path 对象判断模板文件是否存在，然后以 UTF-8 编码读取 JSON 文件。显式指定 encoding="utf-8" 是必要的，否则在 Windows 平台上可能遇到编码问题导致中文注释或内容解析失败。

其次是 replace_placeholders 函数。它遍历字典的键值对，把键名中的 {project_name} 替换为真实项目名。如果值是嵌套字典，继续递归。这一步的核心价值在于：模板可以复用，不需要为每个项目复制一份 JSON。

然后是 create_folders_from_dict 函数。这是完整保留结构的关键。current_path / name 使用 pathlib 的路径拼接方式，不同操作系统下都能正确工作。当 children 中存在嵌套内容时，函数递归调用自身，真正实现了“深一层目录也按模板生成”。

最后是 generate_projects 函数。它接收项目名称列表，循环处理。每个项目名称对应一次模板替换和一次目录创建。如果你要批量创建 30 个项目的目录，只需要把名字放进 project_names 列表即可。

4.4 运行与验证

脚本准备好后，在项目根目录执行：

bash复制cd folder_template_project
python create_folders.py

正常情况下，可以看到以下输出：

code复制[OK] 已生成项目目录: output/demo_project
[OK] 已生成项目目录: output/report_service
[OK] 已生成项目目录: output/data_sync
全部目录已创建完成，请检查 output 目录。

在 Windows 上可以使用 tree /F 查看目录结构，在 Linux 或 macOS 上可以使用 tree 命令。如果系统没有 tree 命令，也可以用 Python 的 os.walk 写一个简单的遍历脚本。先看 output/demo_project 目录：

code复制output/demo_project/
├── config/
├── docs/
│   ├── api/
│   └── meeting/
├── scripts/
│   ├── build/
│   └── deploy/
├── src/
│   └── main/
│       └── java/
├── test/
│   └── cases/
└── output/

可以看到，模板中的每一层结构都被完整保留。src 下的 main 和 java 两层嵌套没有被拍平，docs 下的 api 和 meeting 也没有缺失。

4.5 结果说明

整个脚本的执行流程如下：

1. 读取 template.json，得到模板字典。
2. 依次处理项目名称列表。
3. 对每个项目名称，递归替换字典键名中的 {project_name}。
4. 从 output 根目录开始，递归创建目录。
5. 打印每个项目目录的生成结果。

因为脚本使用了 exist_ok=True，所以即使多次执行也不会报错。如果你再次运行 python create_folders.py，输出依然是成功的，目录不会被重复创建也不会被覆盖。

4.6 从外部文件读取项目名单

实际工作中，项目名称往往不是手写在脚本里的，而是从 Excel、CSV 或文本文件中读取。下面给出一个简单扩展：假设有一个 projects.txt，每行一个项目名。

文件路径：folder_template_project/projects.txt

code复制demo_project
report_service
data_sync

可以把 main() 函数中的 project_names 改成从文件读取：

python复制def read_project_names(file_path):
    """
    从文本文件读取项目名称，每行一个，忽略空行和井号注释。
    """
    names = []
    with open(file_path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line and not line.startswith("#"):
                names.append(line)
    return names


def main():
    template_path = "template.json"
    output_root = "output"
    names_file = "projects.txt"

    project_names = read_project_names(names_file)
    if not project_names:
        print("项目名单为空，请先配置项目名称。")
        sys.exit(1)

    generate_projects(project_names, template_path, output_root)
    print("全部目录已创建完成，请检查 output 目录。")

这样做的好处是业务人员只需要维护一个文本文件，不需要理解 Python 代码。如果你愿意，还可以把数据源换成 Excel 的某一列，用 pandas.read_excel 读取，但受篇幅所限，本文不过多展开。

5. 常见问题与排查思路

5.1 常见问题速查表

先给出一份常见问题速查表，方便读者快速定位。

5.2 模板 JSON 层级错误

这是新手最容易犯的错误。在 JSON 中，每一层嵌套都用花括号 {} 表示，多一个或少一个括号都会改变层级。

错误示例：

json复制{
  "project": {
    "docs": {
      "api": {},
      "meeting": {}
    }
    "src": {}
  }
}

上面这段 JSON 中，"src": {} 和 "meeting": {} 之间缺少逗号，直接导致 JSON 解析失败。另一个常见问题是把子目录写成了数组而不是对象，例如 "docs": ["api", "meeting"]，这样脚本遍历字典时拿到的值是列表而不是字典，也会引发异常。建议在写完模板后先做一次 JSON 合法性校验，可以用 VS Code 自带的 JSON 解析，也可以使用 Python 的 json.load 进行测试。

5.3 递归深度不足

如果脚本只处理一层目录，说明递归调用没有生效。检查 create_folders_from_dict 函数中是否对嵌套字典执行了递归。一种常见的错误写法是只创建当前层的目录，而没有在 children 非空时继续调用自身：

python复制# 错误示例：只创建一层目录
def create_folders_from_dict(current_path, tree_dict):
    for name in tree_dict.keys():
        (current_path / name).mkdir()

这种写法只能创建一级目录，docs/{api} 这种两层以上的结构会丢失。正确做法是遍历 items()，拿到值后判断是否为字典，是字典就递归。

5.4 Windows 路径长度限制

在 Windows 系统中，完整路径超过 260 个字符时，部分操作会失败。如果模板层级很深，或者项目名称很长，可能触发这个问题。解决方式有几种：一是缩短模板层级和命名长度；二是启用 Windows 的长路径支持；三是改用短路径符号链接。对于普通业务场景，推荐第一种方案，即控制模板目录层级和名称长度。

5.5 权限问题

如果把输出目录指向系统关键目录，或者使用没有写权限的服务账号执行脚本，会得到 PermissionError。排查顺序是：先确认目标目录的写权限，再确认脚本运行账号的权限，最后检查是否被安全软件拦截。实际上，创建目录脚本在设计上不应该需要管理员权限，建议始终把输出目录指向普通用户可读写的业务目录。

6. 最佳实践与工程建议

6.1 模板与脚本分离

模板文件应该和脚本独立存放，尽量不要把模板字典硬编码在 Python 代码里。模板单独维护有几个好处：一是非开发人员也可以修改目录规范，不需要碰代码；二是模板变更可以走文件的版本管理，改了什么一目了然；三是同一套脚本可以搭配多套模板使用，适用于不同类型的项目。

例如，数据仓库项目模板和 Java 后端项目模板显然不同，但脚本可以复用。只需要在调用时传入不同的模板文件路径即可。

6.2 目录名命名规范

模板中的目录名最好遵循统一的命名规范。建议使用小写字母加下划线，例如 config、test_cases，避免空格和特殊符号。使用空格会导致路径拼接时需要额外处理，而且大多数团队规范里也不推荐。如果你要生成的是 Java 项目，可以参考 Maven 的标准目录结构；如果是数据项目，可以参考数据仓库分层规范。

6.3 日志输出与错误追踪

本文示例中的 print 是简化做法，适合小规模场景。如果要在生产环境或团队内部批量使用，建议引入 logging 模块，把创建结果写入日志文件，方便排查问题。

python复制import logging

logging.basicConfig(
    filename="folder_creator.log",
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
)

logger = logging.getLogger(__name__)

# 在生成目录时调用
logger.info("已生成项目目录: %s", output_root / project_name)

注意日志记录的时机：建议先记录输入参数，再记录每个目录的创建结果，最后记录整体完成状态。这样出问题时可以通过日志回溯是哪个项目、哪个路径出错。

6.4 先校验模板，再创建目录

在真正创建目录前，先做一次模板校验，能节省大量排错时间。校验内容包括：模板根节点是否为字典、键名是否为空、是否存在不合法的路径字符、是否包含 Windows 保留设备名（如 con、aux）等。可以在 load_template 之后增加一个 validate_template 函数。

python复制import re

INVALID_PATH_CHARS = re.compile(r'[<>:"|?*\x00-\x1f]')


def validate_template(tree_dict):
    """
    校验模板字典中的目录名是否合法。
    不合法时抛出 ValueError。
    """
    for key, value in tree_dict.items():
        if not key:
            raise ValueError("目录名不能为空")
        if INVALID_PATH_CHARS.search(key):
            raise ValueError(f"目录名包含非法字符: {key}")
        if isinstance(value, dict):
            validate_template(value)

这段代码用正则表达式匹配 Windows 和常见文件系统中不允许的字符。需要注意的是，检查模板和检查最终替换后的目录名应该分开：模板里可能包含 {} 占位符，而替换后的名字才需要最终校验。更好的做法是替换完成之后再执行一次 validate_template。

6.5 生产环境注意事项

如果这个脚本要服务于团队或者上线到运维平台，需要额外注意几点。

第一，执行前备份。虽然创建目录不会删除已有数据，但为了安全，仍然建议在执行前记录目标目录下已有的文件清单，异常时可以对照排查。如果脚本将来扩展为“目录结构同步”，即发现模板中不存在的目录后删除，那备份就更加必要，并且要严格限制删除逻辑的权限范围。

第二，最小权限原则。如果脚本在 CI/CD 流水线中运行，应该使用权限最小化的服务账号，只授予目标目录的写权限，不要使用 root 或管理员账号。

第三，执行前打印计划。可以先运行一个 --dry-run 参数，脚本只打印将要创建的目录列表，不真正创建目录。这是生产环境变更前非常实用的做法。

python复制def preview_folders_from_dict(current_path, tree_dict, result_list):
    for name, children in tree_dict.items():
        new_path = current_path / name
        result_list.append(str(new_path))
        if children:
            preview_folders_from_dict(new_path, children, result_list)
    return result_list

在正式创建之前调用这个函数，把结果打印出来给操作人确认，可以避免因模板错误而批量产生了错误目录。

7. 总结与学习路线

本文围绕“按模板批量创建文件夹并保留结构”这一需求，完整实现了一个可复用的 Python 脚本。核心收获可以归纳为三点：一是理解了目录模板的设计方式，JSON 嵌套字典是最适合程序递归处理的结构；二是掌握了递归遍历和目录创建的关键写法，尤其是 Path.mkdir(parents=True, exist_ok=True) 对保留层级和幂等性的作用；三是了解了批量创建场景下的工程化处理，包括占位符替换、外部名单读取、日志记录与安全建议。

如果希望进一步扩展，可以往以下几个方向继续深入。

第一个方向是模板语法增强。目前的占位符只支持 {project_name}，可以扩展为 {year}、{module_name} 等多个自定义参数，甚至支持正则表达式匹配键名。

第二个方向是同时生成文件。目录结构只是项目初始化的第一步，很多团队还需要在每个目录下生成默认文件，例如 README.md、config.ini 或 .gitkeep。可以把模板进一步升级，让每个节点既能包含子目录，又能包含待生成文件列表。

第三个方向是图形化配置。如果团队成员不熟悉 JSON，可以做一个简单的 Web 页面或桌面工具，让用户用鼠标拖拽生成模板，然后后台调用脚本执行。这一方向适合做内部效率工具的开发者参考。

第四个方向是与 Git 仓库初始化流程结合。调用 git init 之后自动执行目录生成脚本，再自动生成 .gitignore，把项目初始化全流程串起来。

最后建议读者不要只看代码，亲手实践一遍效果更好：先复制本文的模板和脚本运行一次，再修改模板增加自己的目录层级，最后尝试用 projects.txt 批量生成多个项目。只有自己踩过一次缩进错误、调过一次编码问题，才能真正理解脚本里每一行代码存在的必要性。如果本文对你有帮助，可以收藏备用，后续遇到项目初始化或目录规范化需求时直接参考这个方案。