如何为 README 创建目录树
目录树能让读者在打开代码仓库之前,就了解路由、组件、配置和文档分别放在哪里。
真正有用的目录树并不是把每个文件原样罗列出来,而是一张聚焦的项目地图:隐藏生成内容、控制合适的展示深度,并解释真正重要的文件。
快速做法
- 打开目录树生成器,导入文件夹、代码仓库、ZIP 或已有目录树。
- 隐藏依赖和构建产物,让结果聚焦源码结构。
- 保留合适的展示深度,为新读者需要了解的路径添加注释。
- 在树样式中选择连接符和注释排版。
- 下载 Markdown,或将复制的文本放进 README 的围栏代码块。
导入项目结构不会重命名、移动或修改任何原始文件。

截图是在真实编辑器中整理的小型示例。下方提供了可以直接复制的完整目录树,不需要准备 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。这是期望的起点,而不是硬性边界;已注释路径较长时,仍可能需要更多空间。没有说明必要的行不必为了“对齐”而补一条注释。

间距设置只调整留白,不能保证不同字体、中英文混排或 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
```
为什么注释看起来没有对齐?
先区分布局策略与渲染问题:按父目录不会把所有注释放在同一列,自适应也可能根据路径长度安排不同位置。如果希望整棵树只有一列注释,先选择全局单列。
如果同一份文本粘贴后仍与预览不同,可以依次检查:
- 确认目录树位于围栏代码块中,而不是普通段落或 Markdown 列表。
- 使用等宽字体和空格缩进;不同查看器的 Tab 宽度可能不同。
- 在副本中去掉 emoji 或混合宽度字符,对比是否由字体回退造成。
- 如果目标环境仍显示不理想,可以缩短长注释、改用紧随路径,或将宽树拆成几个小示例。
调整间距改变的是留白,而不是字体本身的字符宽度。在一个编辑器中看起来对齐,并不保证在所有浏览器和 Markdown 查看器中都一样。
哪些操作在本地,哪些需要联网?
本地文件夹处理、本地 ZIP 解析、编辑、复制和导出都在浏览器中完成,生成目录树无需上传项目文件正文。仓库和远程 ZIP 导入会连接你选择的来源。
AI 注释是可选功能,使用你提供的上下文,不会自动读取项目源文件。应用前请核对建议,数据处理详情见隐私政策。
README 检查清单
发布目录树之前,请确认它:
- 优先展示新贡献者最需要了解的文件和文件夹
- 隐藏依赖、构建产物、缓存和其他无关内容
- 使用在移动端也容易阅读的展示深度
- 解释重要入口和架构边界
- 根据目标环境选用合适的 ASCII 或 Unicode 连接符
- 放在
text代码块中,确保间距得到保留 - 不会暴露私有文件、密钥或无关的本地路径
项目结构发生变化后,最好重新从项目源生成目录树,而不是手动修补旧连接符的间距。