在开发者社区中，文件夹结构往往被视为“小事一桩”——代码能跑就行。但当你面对一个不断增长的静态网站或基于 CMS 的项目，混乱的目录会迅速拖慢开发效率、增加协作成本。究竟什么样的文件夹结构才是“最佳”选择？这个问题没有唯一答案，但经过多年实践，业内已形成若干被广泛认可的范式。本文将从静态站点和 CMS 两大场景出发，为你拆解最实用的组织策略。

一、为什么文件夹结构至关重要？

良好的结构不仅是整洁问题，它直接关乎：

  • 可维护性：新成员能快速定位文件，无需依赖开发者记忆。
  • 可扩展性：新增页面、组件或功能时无需重构整个项目。
  • 构建效率：多数构建工具（如 Vite、Webpack）依赖明确的路径规则进行依赖分析和缓存。
  • 部署安全性：合理的结构能避免将敏感配置或临时文件暴露到生产环境。

二、静态网站的黄金结构：以 Hugo/11ty 为例

对于小型静态网站（纯前端、不依赖运行时后端），最流行的模式是“内容-模板-资产”三分法。以 Hugo 风格的惯例为例：

my-site/
├── content/          # 所有内容（Markdown、JSON 等）
│   ├── _index.md
│   ├── blog/
│   └── about.md
├── layouts/          # HTML 模板（Go 模板、Nunjucks 等）
│   ├── _default/
│   ├── partials/
│   └── index.html
├── static/           # 原始资产（图片、字体、PDF 等）
│   ├── images/
│   ├── fonts/
│   └── favicon.ico
├── assets/           # 需预处理的资产（Sass、TypeScript）
│   ├── css/
│   ├── js/
│   └── images/
├── data/             # 结构化数据（YAML/JSON）
├── config.toml       # 站点配置
└── themes/           # 主题（可选）

要点：content 与 layouts 严格分离，确保内容创作者只需关注 Markdown，不必触碰 HTML。assets 和 static 的区分则取决于是否需构建工具处理。对于纯 HTML/CSS/JS 项目，可合并为 /src 和 /dist，但需明确源文件与输出文件的关系。

三、CMS 类网站的结构：以 WordPress 和 Strapi 为例

基于 CMS 的开发者网站通常包含后端逻辑、数据库迁移、插件等。以 Strapi 这种无头 CMS 为例，推荐如下结构：

my-cms-project/
├── src/
│   ├── admin/          # 管理面板自定义
│   ├── api/            # API 端点与控制器
│   │   ├── article/
│   │   │   ├── controllers/
│   │   │   ├── services/
│   │   │   └── routes/
│   │   └── ...
│   ├── extensions/     # 插件扩展
│   └── middlewares/
├── config/            # 环境配置（database.js, server.js）
├── public/            # 前端静态文件（如构建后的 React 应用）
├── exports/           # 数据导出与备份
├── node_modules/
├── package.json
├── .env               # 环境变量（不提交到仓库）
└── Dockerfile

关键原则：配置与代码分离。config/ 中不应包含密钥，.env 文件通过 .gitignore 排除。api 层按业务模块划分，而非按文件类型（controller、service 混放）。这在大型项目中能显著降低认知负荷。

对于 WordPress 这种传统 CMS，开发者常采用 Sage 或 Bedrock 等现代框架，其结构类似：

wp-project/
├── app/               # 主题与插件
│   ├── themes/
│   │   └── mytheme/
│   │       ├── resources/  # 源码（Sass、ES6）
│   │       ├── dist/       # 编译后文件
│   │       ├── templates/  # PHP 模板
│   │       └── package.json
│   └── plugins/
├── config/            # 环境配置（wp-config.php 的替代）
├── web/               # WordPress 核心（通过 Composer 管理）
├── .env
└── composer.json

这种结构将 WordPress 核心视为依赖，不直接修改，提升了更新安全性。

四、通用建议：你该如何选择？

  1. 先明确项目类型：纯展示站 → 静态结构；带后端管理 → CMS 结构。
  2. 遵循框架约定：框架（如 Hugo、Next.js）通常推荐特定结构，优先遵守可减少配置复杂度。
  3. 模块化而非扁平化：页面、组件、API 按功能拆分子目录，避免单一文件夹内塞入数百个文件。
  4. 区分“源码”与“输出”：确定 /src 和 /dist 或 /public 的边界，并在 .gitignore 中忽略构建产物。
  5. 文档化结构原因：在 README 中简要说明目录用途，尤其是非直观的文件夹（如 _data、_includes）。

五、结论：最佳结构是“演变”出来的

没有放之四海而皆准的“最佳”文件夹结构。小团队初期可用极简格局，随着项目膨胀逐步重构。关键在于一致性：一旦选定范式，团队成员需严格遵循。对于静态网站，坚持“内容与表现分离”；对于 CMS，坚守“配置与代码分离”。这种纪律，比任何花哨的目录树都更重要。

建议开发者抄录上述常见结构作为起点，然后按需剪裁——这才是专业之道。毕竟，好的结构不是一次设计完成的，而是在每一次迭代中持续进化的产物。