跳到主要内容
操作指南阅读 6 分钟更新于 2026-11-07

如何为 README 创建目录树

目录树能让读者在打开代码仓库之前,就了解路由、组件、配置和文档分别放在哪里。

真正有用的目录树并不是把每个文件原样罗列出来,而是一张聚焦的项目地图:隐藏生成内容、控制合适的展示深度,并解释真正重要的文件。

快速做法

  1. 打开目录树生成器,导入文件夹、代码仓库、ZIP 或已有目录树。
  2. 隐藏依赖和构建产物,让结果聚焦源码结构。
  3. 保留合适的展示深度,为新读者需要了解的路径添加注释。
  4. 在树样式中选择连接符和注释排版。
  5. 下载 Markdown,或将复制的文本放进 README 的围栏代码块。

导入项目结构不会重命名、移动或修改任何原始文件。

目录树编辑器中的精简 Next.js 结构、四条注释和导入选项

截图是在真实编辑器中整理的小型示例。下方提供了可以直接复制的完整目录树,不需要准备 Next.js 项目也能跟着操作。

从真实项目开始

在导入标签页中,根据手头的来源选择入口:

来源操作
本地文件夹点击文件夹,或直接拖入导入区域
GitHub / GitLab 仓库点击在线仓库 / ZIP,输入仓库 URL
本地 ZIP点击 ZIP,或拖入压缩包
远程 ZIP点击在线仓库 / ZIP,输入压缩包 URL
已保存的目录树点击树文件,导入支持的文本或结构化目录树文件

如果已经有终端 tree 输出,也可以粘贴到可编辑的文本树面板,再选择应用整棵树(Windows/Linux 快捷键为 Ctrl+Shift+Enter)。它会替换当前展示的结构;仅应用注释用于更新现有树的说明,不是导入另一套目录层级。

dir-tree 会把不同来源统一转换为可编辑的项目结构。你可以先检查导入结果,再决定 README 中应该保留哪些内容。

排版前先隐藏生成文件

README 应该帮助读者理解项目,而不是复刻磁盘上的每一个文件。调整目录树样式之前,先隐藏依赖、构建产物、缓存、测试覆盖率报告和其他生成目录。

对于 JavaScript 项目,可以先在排除规则中加入以下内容,每行一个 glob:

node_modules
.next
dist
build
coverage
.cache

来源支持读取选项时,如果项目的忽略规则符合展示目的,可以保留启用 .gitignore。修改读取选项后,点击使用当前选项刷新重新读取来源。只想从展示结果中移除某一项时,在可视树中选中它,再使用隐藏节点;这不会删除原始文件。

不同项目需要排除的内容并不完全相同。如果某个生成目录无法帮助读者理解源码结构,就不必把它放进最终结果。

选择合适的展示深度

可以先从两到四层开始,再根据项目特点和 README 的可用空间调整。优先展示新读者需要了解的路径,不必展开每一处实现细节。

导入读取选项中的递归深度用于限制读取层级。也可以折叠文件夹,让当前展示更聚焦;导出前请检查文本预览。对于 monorepo,与其放一棵很宽的大树,不如按需要分别展示几个包的精简结构。

聚焦的目录树更容易维护,也不容易在日常重构后迅速过时。如果读者确实需要更深层的说明,可以链接到单独的架构文档,而不是把整个代码仓库都塞进 README。

注释关键设计,不必逐行说明

只为能帮助新读者理解架构的文件和文件夹添加注释。路由、共享组件、配置、数据访问层和入口文件通常值得说明。

如果文件名已经清楚表达了用途,就不必再重复解释。少量有价值的注释,比每一行都添加说明更容易浏览。

选中文件或文件夹,在节点操作中使用添加注释,或编辑已有说明。注释要回答读者的问题:“页面与布局”比“应用文件夹”更有帮助。也可以主动使用 AI 生成建议,但应用前应结合真实项目核对。

选择注释排版

进入树样式 → 注释样式。希望每条说明紧跟路径时,选择紧随路径;希望纵向浏览说明时,选择对齐。

对齐排版包含三种策略:

策略适合尝试的情况需要了解的行为
自适应路径长短差异比较大在列排版和长路径所需空间之间取得平衡,不代表整棵树只使用一列
全局单列较短的目录树需要统一的注释列所有已注释行共用一列,最长的已注释路径可能将整列向右推
按父目录较大的目录树包含多个分组同一父目录下的节点分别对齐,不同文件夹的注释列可以不同

下图使用全局单列,将首选起始列设为 32。这是期望的起点,而不是硬性边界;已注释路径较长时,仍可能需要更多空间。没有说明必要的行不必为了“对齐”而补一条注释。

文本预览中的四条注释,以及对齐、全局单列和首选起始列 32 设置

间距设置只调整留白,不能保证不同字体、中英文混排或 emoji 在所有环境中都视觉对齐。先在文本预览中选择合适的布局,再检查最终 README 的显示效果。

选择 ASCII 或 Unicode 输出

在 GitHub README 和现代文档中,Unicode 连接符通常更清晰。目标环境的字符支持有限,或其他工具只接受简单标点时,可以使用纯 ASCII 格式。

两种格式都支持注释、复制和导出。根据读者最终查看 README 的环境选择即可。

导出 README 可用的结果

完成过滤和注释后,打开文本预览旁的下载菜单,选择 Markdown。也可以点击复制,将生成的文本放入下方示例中的 text 围栏代码块。

围栏代码块可以保留空格和换行。仍应在最终展示环境中预览 README,因为字体回退、emoji 和中英文混合名称可能影响视觉对齐。

精简的 Next.js 示例

下面是一棵适合小型 Next.js 应用的精简目录树:

next-app/
├── public/                     # 静态资源
├── src/
│   └── app/                    # 页面与布局
│       │── layout.tsx          # 共享布局
│       └── page.tsx
│── next.config.ts              # 框架配置
│── package.json
└── README.md

将目录树粘贴到 Markdown

可以像下面这样把同一份结构粘贴到 README 中:

## 项目结构

```text
next-app/
├── public/                     # 静态资源
├── src/
│   └── app/                    # 页面与布局
│       │── layout.tsx          # 共享布局
│       └── page.tsx
│── next.config.ts              # 框架配置
│── package.json
└── README.md
```

为什么注释看起来没有对齐?

先区分布局策略与渲染问题:按父目录不会把所有注释放在同一列,自适应也可能根据路径长度安排不同位置。如果希望整棵树只有一列注释,先选择全局单列。

如果同一份文本粘贴后仍与预览不同,可以依次检查:

  1. 确认目录树位于围栏代码块中,而不是普通段落或 Markdown 列表。
  2. 使用等宽字体和空格缩进;不同查看器的 Tab 宽度可能不同。
  3. 在副本中去掉 emoji 或混合宽度字符,对比是否由字体回退造成。
  4. 如果目标环境仍显示不理想,可以缩短长注释、改用紧随路径,或将宽树拆成几个小示例。

调整间距改变的是留白,而不是字体本身的字符宽度。在一个编辑器中看起来对齐,并不保证在所有浏览器和 Markdown 查看器中都一样。

哪些操作在本地,哪些需要联网?

本地文件夹处理、本地 ZIP 解析、编辑、复制和导出都在浏览器中完成,生成目录树无需上传项目文件正文。仓库和远程 ZIP 导入会连接你选择的来源。

AI 注释是可选功能,使用你提供的上下文,不会自动读取项目源文件。应用前请核对建议,数据处理详情见隐私政策。

README 检查清单

发布目录树之前,请确认它:

  • 优先展示新贡献者最需要了解的文件和文件夹
  • 隐藏依赖、构建产物、缓存和其他无关内容
  • 使用在移动端也容易阅读的展示深度
  • 解释重要入口和架构边界
  • 根据目标环境选用合适的 ASCII 或 Unicode 连接符
  • 放在 text 代码块中,确保间距得到保留
  • 不会暴露私有文件、密钥或无关的本地路径

项目结构发生变化后,最好重新从项目源生成目录树,而不是手动修补旧连接符的间距。

打开 dir-tree,为你的 README 整理目录树。

准备生成你的第一棵目录树了吗?

免费使用目录树编辑器,无需注册或安装。

在浏览器中试用 dir-tree