GitHub项目目录结构设计：从入门到精通的最佳实践指南

1. 项目概述：为什么我们需要关注GitHub项目目录结构？

如果你刚开始接触GitHub，或者已经上传过几个项目，但总觉得自己的仓库看起来有点“乱”，那么这篇文章就是为你准备的。我见过太多新手甚至是有几年经验的开发者，他们的GitHub仓库就像一个杂物间，文件随意堆放，README写得语焉不详，别人点进来根本不知道从何看起，更别说参与贡献了。一个好的项目目录结构，就像一本书的清晰目录，或者一家商店的合理布局，它不仅仅是“好看”，更是项目可维护性、可协作性和专业度的直接体现。

简单来说，一个清晰的项目目录结构能解决几个核心问题：第一，降低新成员的入门门槛。无论是你的团队成员，还是社区里想参与贡献的开发者，一个标准的目录能让他们在5分钟内找到所有关键文件（如源码、文档、配置、测试）。第二，提升项目的可维护性。当项目规模增长时，一个糟糕的结构会让你自己都迷失在文件海洋里。第三，它是项目的“第一印象”。一个结构清晰、文档齐全的仓库，往往能吸引更多Star、Fork和贡献者，这是开源项目成功的关键因素之一。

在接下来的内容里，我不会只给你一个“标准答案”，因为不同语言、不同规模的项目结构各有不同。我会带你拆解那些顶级开源项目的通用模式，解释每个目录和文件存在的“为什么”，并分享我在维护多个开源项目过程中踩过的坑和总结出的最佳实践。无论你是想整理自己的个人项目，还是准备启动一个严肃的开源计划，这些经验都能让你少走弯路。

2. 核心目录与文件解析：从根目录开始

当你克隆或浏览一个GitHub项目时，第一眼看到的就是根目录下的文件和文件夹。这些是项目的“门面”和“总纲”。理解它们的用途，是读懂任何项目的第一步。

2.1 必选文件：项目的身份证与说明书

每个项目都应该包含几个关键文件，它们向所有访问者传递了最基本、最重要的信息。

README.md：项目的核心说明书这是整个仓库中最重要的文件，没有之一。它通常以Markdown格式编写，并默认显示在仓库首页。一个优秀的README应该包含：

• 项目名称与徽章（Badges）：清晰的项目名，以及展示构建状态、测试覆盖率、版本号、许可证等的徽章（通常来自Shields.io）。这些徽章是项目健康度和专业度的直观体现。
• 简短描述：用一两句话说明这个项目是做什么的，解决什么问题。
• 功能特性（Features）：以列表形式列出核心功能，让用户快速了解价值。
• 快速开始（Quick Start）：这是最关键的章节。提供最简短的命令或步骤，让用户能在几分钟内把项目跑起来。例如，对于一个Node.js项目，可能就是npm install && npm start。
• 详细文档链接：如果文档很庞大，README里放不下，一定要在这里给出文档目录的链接（通常指向docs/目录）。
• 如何贡献（Contributing）：引导他人如何为项目做贡献，可以链接到CONTRIBUTING.md文件。
• 许可证（License）：明确声明项目使用的开源许可证，可以链接到LICENSE文件。

实操心得：写README时，请始终站在一个完全不了解该项目的新手角度。避免使用内部术语，确保“快速开始”章节的每一步都经过验证，可以复制粘贴执行。我习惯在写完README后，找一个完全没接触过项目的朋友，让他按照步骤操作，记录下所有卡住的地方并进行修改。

LICENSE：项目的法律基石这个文件定义了他人可以使用、修改和分发你代码的规则。没有许可证的文件，在法律上默认是保留所有权利的，这意味着别人甚至不能合法地使用你的代码。对于开源项目，选择一个合适的许可证至关重要。常见的有：

• MIT：非常宽松，允许任何用途，只需保留原许可证声明。
• Apache 2.0：类似MIT，但明确提供了专利授权，并对修改后的文件有更明确的声明要求。
• GPL系列（如GPL-3.0）：具有“传染性”，任何使用了GPL代码的衍生作品也必须以GPL开源。 在GitHub创建仓库时，可以直接选择一个许可证模板。绝对不要在一个打算开源的项目中省略此文件。

.gitignore：保持仓库清洁的守门员这个文件告诉Git哪些文件或目录不应该被纳入版本控制。比如编译产物（node_modules/,dist/,*.class）、本地配置文件（.env）、IDE项目文件（.idea/,.vscode/）等。为你的项目语言或框架选择合适的.gitignore模板（可以在 gitignore.io 生成），能有效避免将无关的、庞大的或包含敏感信息的文件提交到仓库。

2.2 核心目录：功能模块的物理分区

根目录下的文件夹将代码和资源按逻辑进行划分。虽然具体名称可能因项目而异，但以下模式被广泛接受。

src/或lib/：源代码之家这是项目核心逻辑所在。所有自己编写的源代码（如.py,.js,.java,.go文件）都应该放在这里或其子目录下。使用src/(source的缩写) 是最常见的做法。其内部结构又能进一步按模块、层级或功能划分，例如：

src/ ├── components/ # 可复用的UI组件（前端项目） ├── utils/ # 工具函数 ├── api/ # API接口层 ├── models/ # 数据模型 └── index.js # 主入口文件

将源代码集中管理，与配置文件、文档、构建脚本等分离，是软件工程中“关注点分离”原则的体现。

tests/或__tests__：质量保障区专门存放所有测试代码的目录。与src/并列放置tests/是一种常见结构。另一种流行做法（尤其在JavaScript生态中）是在src/每个模块旁边放置一个__tests__目录，使测试文件紧邻被测试的源码文件。无论哪种方式，明确区分测试代码和生产代码都是好习惯。测试目录内部结构最好能镜像src/的结构，便于查找和管理。

docs/：项目知识库当README不足以容纳所有文档时，就需要docs/目录。这里可以存放详细的API文档、设计文档、用户手册、教程等。很多项目会使用像MkDocs、Docusaurus或VuePress这样的文档生成器，此时docs/目录下就是这些工具的源文件（通常是Markdown），构建后会生成静态网站并托管在GitHub Pages上。

config/或conf/：配置管理中心存放各种配置文件，如应用运行时配置、数据库连接配置、日志配置等。重要原则：这里只存放配置文件的示例或模板（如config.example.yaml,.env.example），而将包含敏感信息（如密码、密钥）的实际配置文件（如.env）添加到.gitignore中。这样既提供了配置范例，又避免了泄露机密。

scripts/或tools/：自动化工具箱存放用于项目构建、部署、代码生成或其他自动化任务的脚本文件。例如，一个scripts/build.sh或scripts/deploy.js。将这些脚本集中管理，而不是散落在根目录，能让项目结构更清晰，也方便团队其他成员使用。

3. 不同技术栈的目录结构实践

通用的模式了解后，我们来看看在不同语言和框架的生态中，有哪些被社区广泛认可和工具链默认支持的最佳实践。遵循这些约定俗成的结构，能让你的项目更容易被同领域开发者理解，也能更好地与配套工具（如构建工具、测试框架、包管理器）集成。

3.1 前端项目（React/Vue）

现代前端项目，尤其是使用React或Vue等框架的单页应用（SPA），其结构通常由脚手架工具（如Create React App, Vue CLI, Vite）生成，已经非常标准化。

React项目（基于Create React App或Vite）常见结构：

my-react-app/ ├── public/ # 静态资源（如index.html、favicon.ico），构建时会直接复制到输出目录 ├── src/ # 所有源代码 │ ├── assets/ # 图片、字体、样式等静态资源（会被构建工具处理） │ ├── components/ # 可复用的UI组件 │ ├── pages/ # 页面级组件（对应路由） │ ├── hooks/ # 自定义React Hooks │ ├── contexts/ # React Context定义 │ ├── services/ # API请求层、业务逻辑 │ ├── utils/ # 工具函数 │ ├── App.jsx # 根组件 │ └── index.jsx # 应用入口，渲染根组件到DOM ├── package.json # 项目依赖和脚本定义 └── vite.config.js # 或 webpack.config.js，构建配置

核心思路：src/内按**功能特性（Feature）或文件类型（Type）**组织。目前更推荐按功能特性组织，例如src/user/目录下包含该用户功能相关的组件、钩子、样式和逻辑，内聚性更强。

Vue项目（基于Vue CLI或Vite）常见结构：

my-vue-app/ ├── public/ # 同React ├── src/ │ ├── assets/ │ ├── components/ # 公共组件 │ ├── views/ # 或 pages/，页面组件 │ ├── router/ # 路由配置 │ ├── store/ # Vuex或Pinia状态管理 │ ├── composables/ # Vue组合式函数（类似React Hooks） │ ├── App.vue # 根组件 │ └── main.js # 应用入口 ├── package.json └── vite.config.js

Vue项目的结构与React高度相似，体现了现代前端开发的共通模式。

注意事项：避免在src/components/下创建过深的嵌套。如果某个组件只被一个页面或特性使用，考虑将其放在该页面或特性的目录下（即“共用的放components，私有的放features/xxx”）。这能有效防止components目录膨胀成难以管理的“垃圾场”。

3.2 后端/全栈项目（Node.js, Python, Go）

后端项目结构更侧重于业务逻辑、数据模型和API的分层。

Node.js（Express/Koa）项目常见结构：

my-express-api/ ├── src/ │ ├── config/ # 配置文件（数据库、应用等） │ ├── controllers/ # 控制器，处理请求和响应 │ ├── models/ # 数据模型（Mongoose Schema、Sequelize Model等） │ ├── routes/ # 路由定义，将URL映射到控制器 │ ├── middleware/ # 中间件（认证、日志、错误处理） │ ├── services/ # 业务逻辑层，封装复杂操作 │ ├── utils/ # 工具函数 │ ├── validators/ # 请求数据验证逻辑 │ └── app.js # Express应用实例 ├── tests/ # 集成测试、单元测试 ├── package.json └── server.js # 或 index.js，服务启动入口

这种“分层架构”将不同的职责分离，使代码更易于测试和维护。services/层的引入是关键，它避免了控制器变得过于臃肿，将核心业务逻辑独立出来。

Python（Django/Flask）项目常见结构：

• Django：Django有严格的项目（Project）和应用（App）概念。一个项目目录通常如下：

  my_django_project/ ├── manage.py # Django命令行工具入口 ├── my_project/ # 项目配置目录（与项目同名） │ ├── __init__.py │ ├── settings.py # 主配置文件 │ ├── urls.py # 项目级URL路由 │ └── wsgi.py └── apps/ # 自定义应用目录（非Django默认，但推荐） ├── blog/ # 一个功能应用，如博客 │ ├── migrations/ # 数据库迁移文件 │ ├── models.py │ ├── views.py │ └── ... └── users/ # 另一个功能应用，如用户管理

  将不同功能拆分为独立的“应用”，是Django鼓励的高内聚、低耦合设计。
• Flask：Flask更轻量，结构更自由，但通常遵循类似模式：

  my_flask_app/ ├── app/ │ ├── __init__.py # 应用工厂函数 │ ├── models.py # 数据模型 │ ├── routes/ # 蓝图（Blueprints）目录，用于模块化路由 │ │ ├── main.py │ │ └── api.py │ ├── templates/ # Jinja2模板 │ ├── static/ # 静态文件 │ └── config.py # 配置类 ├── tests/ ├── migrations/ # 如果使用Flask-Migrate ├── requirements.txt # Python依赖 └── run.py # 开发环境启动脚本

Go项目结构：Go语言社区推崇简洁和明确。标准项目布局（参考golang-standards/project-layout）虽然非官方，但被广泛采用：

my-go-service/ ├── cmd/ # 应用程序入口目录，每个子目录是一个可执行文件 │ └── myapp/ # 例如，这里放 main.go │ └── main.go ├── internal/ # 私有应用程序代码，外部项目无法导入 │ ├── handler/ # HTTP处理器 │ ├── service/ # 业务逻辑 │ └── repository/ # 数据访问层 ├── pkg/ # 公共库代码，可供外部项目导入 │ └── utils/ ├── api/ # API定义文件（如Protobuf, Swagger） ├── web/ # 前端静态资源或模板 ├── configs/ # 配置文件 ├── scripts/ # 脚本 ├── deployments/ # 部署配置（Docker, k8s） ├── test/ # 测试数据或外部测试 ├── go.mod └── README.md

cmd/和internal/的划分是Go项目的精髓，清晰地定义了代码的可见性边界。

3.3 其他常见模式

examples/或demo/：存放如何使用本项目库的示例代码。对于SDK、库或框架类项目尤其重要，是比文档更直观的教学材料。build/或dist/：构建产物的输出目录。务必在.gitignore中忽略此目录，不要将构建后的二进制文件或打包文件提交到源码仓库。vendor/：在一些语言中（如Go的早期版本，或使用dep时），用于存放项目依赖的第三方代码副本，以确保构建的一致性。现代Go使用go.mod后，此目录已不常见。

4. 高级结构与元文件管理

当项目变得复杂，或者你希望它更专业、更自动化时，就需要关注一些更高级的目录和文件。

4.1 协作与流程规范文件

这些文件定义了项目协作的“游戏规则”，对于开源项目或多人团队至关重要。

CONTRIBUTING.md：贡献者指南这个文件详细说明了他人如何为你的项目做贡献。内容应包括：

• 如何报告Bug：提供Issue模板或明确需要的信息（如环境、复现步骤）。
• 如何提议新功能：同样可以提供Feature Request的模板。
• 开发环境搭建步骤：比README中的“快速开始”更详细，包括如何获取源码、安装依赖、运行测试等。
• 代码风格指南：链接或说明项目遵循的代码规范（如ESLint, Prettier, Black, Gofmt）。
• 提交流程：是否使用Fork & Pull Request模式？提交信息有何规范？ 一份清晰的CONTRIBUTING.md能极大降低贡献者的心理门槛和操作成本。

CODE_OF_CONDUCT.md：行为准则这是一个声明，旨在为所有参与者（包括维护者和贡献者）营造一个开放、友善、无骚扰的协作环境。通常采用“贡献者公约”（Contributor Covenant）等现成模板。它表明了项目维护者对社区健康度的重视。

CHANGELOG.md或 GitHub Releases：更新日志记录每个版本中重要的变更（新增功能、修复的Bug、不兼容的改动）。遵循 Keep a Changelog 这样的规范能让日志更清晰可读。现在很多开发者更倾向于直接使用GitHub的Releases功能，它集成了标签（Tag）和更新日志，并可以附加二进制文件，非常方便。

4.2 自动化与质量保障配置

现代项目开发离不开CI/CD（持续集成/持续部署）和代码质量工具，它们的配置文件通常放在根目录。

CI/CD配置文件：如.github/workflows/目录下的YAML文件（GitHub Actions），或者.gitlab-ci.yml(GitLab CI)，.travis.yml(Travis CI)等。这些文件定义了代码推送后自动运行的测试、构建、部署流水线。

.github/workflows/ ├── test.yml # 在PR或推送到主分支时运行测试 └── deploy.yml # 在打上新标签时自动构建并发布到包管理器或服务器

代码质量与格式化配置：

• .eslintrc.js,.prettierrc：用于JavaScript/TypeScript的代码检查和格式化配置。
• .pylintrc,pyproject.toml：用于Python的代码检查（Pylint）和格式化（Black）配置。
• .golangci.yml：用于Go语言的多种Lint工具聚合配置。
• .editorconfig：定义基本的代码风格（如缩进、换行符），帮助在不同编辑器中保持一致性。

将这些工具的配置文件纳入版本控制，可以确保团队所有成员和CI系统使用同一套质量规则。

4.3 包管理与依赖管理

这是项目与生态系统交互的接口。

package.json(Node.js)：不仅仅是依赖列表，它还定义了项目元数据、可执行脚本（scripts）、入口文件等。scripts字段是强大的自动化入口，例如npm run build,npm test。requirements.txt或Pipfile或pyproject.toml(Python)：管理Python依赖。go.mod(Go)：定义Go模块、依赖和版本。Cargo.toml(Rust)：Rust项目的清单文件。pom.xml或build.gradle(Java)：Maven或Gradle的构建配置文件。

这些文件是项目的“配方”，必须精心维护。一个常见的最佳实践是同时提供锁文件（如package-lock.json,Pipfile.lock,Cargo.lock），用于锁定依赖的确切版本，确保在不同环境下的构建一致性。锁文件应该被提交到版本库中。

5. 实战：从零搭建一个结构清晰的项目

理论说了这么多，我们动手为一个假设的“用户管理微服务API”（使用Node.js + Express）设计一个完整的目录结构，并解释每一步的思考过程。

5.1 项目初始化与基础文件

首先，创建项目根目录并初始化Git和npm。

mkdir user-management-service cd user-management-service git init npm init -y

接下来，创建最基础的必要文件：

1. README.md：先写一个骨架，包括项目名、简短描述、快速开始。后续逐步完善。
2. LICENSE：选择MIT许可证，复制内容进去。
3. .gitignore：使用Node.js的模板。可以手动创建，或通过npx gitignore node命令生成。

5.2 设计核心目录结构

根据我们之前讨论的分层架构，创建以下目录：

mkdir -p src/config src/controllers src/models src/routes src/middleware src/services src/utils src/validators tests docs

现在结构如下：

user-management-service/ ├── src/ │ ├── config/ │ ├── controllers/ │ ├── middleware/ │ ├── models/ │ ├── routes/ │ ├── services/ │ ├── utils/ │ └── validators/ ├── tests/ ├── docs/ ├── .gitignore ├── LICENSE ├── README.md └── package.json

5.3 填充内容与逻辑解释

1. 配置层 (src/config/)创建index.js，使用dotenv加载环境变量，并导出一个配置对象。

// src/config/index.js require('dotenv').config(); // 加载 .env 文件 module.exports = { server: { port: process.env.PORT || 3000, }, database: { url: process.env.DATABASE_URL, }, jwt: { secret: process.env.JWT_SECRET, }, };

同时创建.env.example文件，列出所有需要的环境变量，并确保.env在.gitignore中。

2. 数据模型层 (src/models/)这里定义数据结构。假设使用Mongoose（MongoDB ODM）。

// src/models/User.js const mongoose = require('mongoose'); const userSchema = new mongoose.Schema({ username: { type: String, required: true, unique: true }, email: { type: String, required: true, unique: true }, passwordHash: { type: String, required: true }, // ... 其他字段 }, { timestamps: true }); module.exports = mongoose.model('User', userSchema);

3. 业务逻辑层 (src/services/)这是核心。控制器应该很“薄”，只负责接收请求和发送响应，所有复杂逻辑都放在服务层。

// src/services/userService.js const User = require('../models/User'); const bcrypt = require('bcrypt'); class UserService { async createUser(userData) { // 密码哈希处理 const hashedPassword = await bcrypt.hash(userData.password, 10); const user = new User({ ...userData, passwordHash: hashedPassword }); return await user.save(); } async findUserById(id) { return await User.findById(id).select('-passwordHash'); // 不返回密码哈希 } // ... 其他业务方法 } module.exports = new UserService();

4. 控制器层 (src/controllers/)控制器调用服务层，处理HTTP请求和响应。

// src/controllers/userController.js const userService = require('../services/userService'); exports.createUser = async (req, res, next) => { try { const newUser = await userService.createUser(req.body); res.status(201).json({ success: true, data: newUser }); } catch (error) { next(error); // 传递给全局错误处理中间件 } }; exports.getUser = async (req, res, next) => { try { const user = await userService.findUserById(req.params.id); if (!user) { return res.status(404).json({ success: false, message: 'User not found' }); } res.json({ success: true, data: user }); } catch (error) { next(error); } };

5. 路由层 (src/routes/)定义API端点与控制器方法的映射。

// src/routes/userRoutes.js const express = require('express'); const router = express.Router(); const userController = require('../controllers/userController'); const { validateCreateUser } = require('../validators/userValidator'); // 输入验证 router.post('/', validateCreateUser, userController.createUser); router.get('/:id', userController.getUser); // ... 其他路由 module.exports = router;

然后在主应用文件（如src/app.js）中统一引入所有路由。

6. 工具与中间件

• src/middleware/：放置认证中间件auth.js、错误处理中间件errorHandler.js、日志中间件等。
• src/validators/：使用Joi或Express-validator定义请求数据的验证规则。
• src/utils/：放置通用的辅助函数，如密码哈希比较、生成JWT令牌的函数等。

5.4 完善周边设施

1. 测试 (tests/)创建单元测试（针对服务层、工具函数）和集成测试（针对API端点）。使用Jest、Mocha等框架。测试文件结构最好镜像src/。

tests/ ├── unit/ │ └── services/ │ └── userService.test.js └── integration/ └── routes/ └── userRoutes.test.js

2. 文档 (docs/)创建docs/api.md详细描述每个API端点（可以使用Swagger/OpenAPI规范）。创建docs/development.md描述开发环境搭建。

3. 脚本 (scripts/)创建scripts/seed-db.js用于数据库初始化，scripts/start-dev.js用于启动开发服务器（可能集成了nodemon）。

4. 根目录配置文件

• package.json：完善scripts字段，如"start": "node src/server.js","dev": "nodemon src/server.js","test": "jest"。
• .eslintrc.js,.prettierrc：配置代码规范。
• .github/workflows/ci.yml：配置GitHub Actions，在每次推送时运行测试。

经过以上步骤，你就得到了一个结构清晰、职责分离、易于维护和扩展的Node.js后端项目骨架。这个结构不是一成不变的，你可以根据项目具体需求进行调整，但其核心思想——分离关注点、模块化组织、文档与自动化先行——是普适的。

6. 常见问题与避坑指南

在实际操作中，即使遵循了最佳实践，也可能会遇到一些问题。以下是我在多年项目维护中总结的一些常见“坑”及其解决方案。

6.1 结构选择困难症：到底该用哪种？

问题：看了很多模式，不知道自己的小项目该用哪种结构，怕“过度设计”。建议：对于非常小的项目（比如一个简单的工具脚本），一个index.js加一个README.md就足够了。从简单开始，按需演进。当你觉得一个文件里的代码太多，逻辑开始混杂时，就是拆分的时机。一个实用的演进路径是：

1. 单文件。
2. 按功能拆分成多个文件，放在同一目录。
3. 将文件按类型（如controllers,models）归类到不同子目录。
4. 引入更清晰的分层（如增加services层）。 记住，没有“最好”的结构，只有“更适合当前项目规模和团队”的结构。

6.2 配置文件与敏感信息管理

问题：配置文件里包含数据库密码、API密钥，不小心提交到了GitHub。踩坑实录：这是我早期犯过的严重错误。直接提交了包含AWS密钥的.env文件，虽然几分钟后就发现了并重写历史，但依然心惊胆战。标准做法：

1. 永远将.env、config/production.yaml等包含真实敏感信息的文件添加到.gitignore。
2. 提供.env.example或config/config.example.yaml文件，列出所有需要的配置项及其示例值（用假值或空值）。
3. 在README或部署文档中明确说明如何根据示例文件创建真实配置。
4. 考虑使用密钥管理服务（如AWS Secrets Manager, HashiCorp Vault）或在CI/CD环境中直接注入环境变量。

6.3 依赖管理：该提交package-lock.json吗？

问题：package-lock.json或yarn.lock文件体积不小，而且变化频繁，该不该提交？明确结论：应该提交！锁文件的作用是锁定依赖树中所有包的确切版本。提交它能确保：

• 一致性：所有开发者以及CI服务器安装的依赖版本完全一致，避免“在我机器上是好的”这类问题。
• 可追溯性：你可以清楚地知道某个时间点项目依赖的具体版本，便于回滚和排查问题。
• 安装速度：npm/yarn可以利用锁文件进行更快的确定性安装。 只有开发库（library）时，情况略有不同，可能需要考虑不提交锁文件以确保用户能安装到符合语义化版本范围的最新依赖。但对于应用（application）项目，务必提交锁文件。

6.4 文档与代码同步难题

问题：代码更新了，但README和API文档忘了改，导致文档过时。应对策略：

1. 文档即代码：将文档放在源码仓库中（如docs/目录），这样修改代码时，可以方便地在同一个提交（Commit）或拉取请求（Pull Request）中更新文档。Code Review时也要检查文档更新。
2. 自动化：对于API文档，尽量使用Swagger/OpenAPI这类能从代码注释或路由定义中自动生成文档的工具。这样文档永远与代码同步。
3. 将更新文档作为流程的一部分：在团队的开发流程中，明确将“更新相关文档”作为完成一项功能或修复一个Bug的必需步骤。

6.5 如何处理构建产物和生成文件？

问题：dist/,build/,coverage/等目录是否应该提交？黄金法则：由源码通过工具（编译器、打包器、测试框架）生成的文件，都不应该提交到源码仓库。

• 为什么？它们不是源代码，提交它们会造成仓库膨胀、历史混乱，并且可能包含特定于环境的配置。更重要的是，它们可以从源代码重新生成。
• 怎么做？将这些目录（如dist/,build/,node_modules/,.next/,coverage/）添加到.gitignore。
• 例外情况：对于需要通过GitHub Pages部署的文档网站（其HTML/CSS/JS是构建产物），有时会将其构建到docs/或根目录的特定分支（如gh-pages）并提交。这是一种特例，目的是利用GitHub的托管服务。

遵循这些原则和实践，你的GitHub项目仓库将不仅是一个代码存放地，更是一个清晰、专业、易于协作的作品。一个好的结构是项目长期健康发展的基石，花时间在初期搭建好它，会在未来为你和所有参与者节省无数的时间和精力。