前端项目常见目录结构及配置
前端项目常见目录结构及配置

获取一个前端项目，通过目录文件即可知道项目使用了哪些解决方案，每一个文件代表着一个配置，以下总结常见的目录及文件结构，并将持续更新和完善。

一、根目录配置文件

package.json

这是 npm 或 yarn 的核心配置文件，包含项目的基本信息、依赖和脚本。它定义了项目的名称、版本、依赖包以及可以通过 npm run 或 yarn 运行的脚本（如构建、测试和启动）。这个文件帮助你管理项目的依赖和配置，确保项目的一致性。它还包括：

  • scripts: 自定义命令，如 npm start、npm test，使得项目的开发、测试和构建流程更加高效。
  • dependencies 和 devDependencies: 列出生产和开发环境所需的依赖，确保正确的版本管理。
  • engines: 指定 Node.js 的版本要求，确保项目在正确的环境中运行。

package-lock.json、yarn.lock 或 pnpm-lock.yaml

这些锁文件记录了项目中每个依赖的具体版本。它们用于确保依赖的一致性。确保每次安装依赖时，所有团队成员和 CI/CD 环境使用的依赖版本是一致的，防止由于依赖版本变化导致的潜在问题。

  • package-lock.json: 生成于每次运行 npm install，记录确切的依赖树和版本。
  • yarn.lock: Yarn 的锁文件，功能类似于 package-lock.json，确保所有依赖版本的一致性。
  • pnpm-lock.yaml: pnpm 的锁文件，用于记录项目的依赖树和版本，保证一致性。

.gitignore

这个文件告诉 Git 哪些文件和目录应该被忽略，从而避免将不必要的文件（如 node_modules/、编译生成的文件、敏感的环境变量文件等）提交到版本控制系统。

  • node_modules/: 排除依赖文件夹，避免提交大量的第三方库。
  • dist/ 或 build/: 排除构建输出目录，减少版本库的体积。
  • .env: 避免将敏感环境变量文件提交到版本控制系统。

.npmrc 或 .yarnrc

这些文件用于配置 npm 或 Yarn 的设置，例如指定使用的注册表、设置代理服务器等。它们可以帮助你定制包管理工具的行为，适应不同的开发环境需求。

  • registry: 设置包管理工具的注册表，使用私有注册表或不同的公共注册表。
  • cache: 配置缓存目录，提高包管理工具的性能。
  • scripts-prepend-node-path: 设置为 true 可以确保在运行 npm 脚本时，Node.js 的路径被正确配置。

.env 、 .env.*

环境变量文件用于定义应用在不同环境下的配置（如 API 密钥、数据库连接信息等）。通过 .env 文件，你可以设置开发、测试和生产环境所需的配置，而不需要在代码中硬编码这些信息。常见的包括 .env.local、.env.development、.env.production。

  • .env.local: 本地环境专用配置，通常不会被提交到版本控制系统。
  • .env.development: 适用于开发环境的配置。
  • .env.production: 适用于生产环境的配置。

README.md

自述文件是项目的重要文档，提供项目的概述、安装步骤、使用说明和其他关键信息。它帮助新用户和开发者快速了解项目的目的、功能和使用方法。

  • 项目概述: 简要描述项目的目标和功能。
  • 安装步骤: 指导用户如何在本地环境中设置和运行项目。
  • 使用说明: 提供如何使用项目的详细信息。

LICENSE

许可证文件说明了项目的使用和分发权限。它定义了开源或商业许可的条款，确保用户了解如何合法使用和贡献项目代码。

  • 开源许可: 如 MIT、GPL、Apache 等，规定代码的使用、复制和修改条款。
  • 商业许可: 对商业用途的限制和授权。

CHANGELOG.md

变更日志记录了项目的版本变更和修复历史。它按版本列出新增功能、改进、修复和其他重大更改，帮助用户和开发者了解项目的演变。

  • 新增功能: 列出每个版本中添加的新功能。
  • 修复: 描述已解决的错误和问题。
  • 改进: 记录性能改进和用户体验提升。

CONTRIBUTING.md

贡献指南文件提供了如何为项目贡献代码的详细说明。它包括报告问题、提交代码、编码标准、测试要求、贡献者协议和社区规范等，帮助外部开发者理解如何有效地参与项目。

  • 如何报告问题: 指导用户如何提交 bug 报告或功能请求。
  • 提交代码: 说明如何分支、提交和合并代码。
  • 编码标准: 定义项目的代码风格和格式要求。

manifest.json

用于 Progressive Web App (PWA) 的配置文件，定义了应用的图标、名称、启动 URL 等信息。这些设置帮助浏览器正确展示和启动 PWA 应用。

  • name: 应用的名称。
  • short_name: 应用的短名称，通常用于主屏幕图标。
  • icons: 应用图标的配置，包括不同尺寸的图标。
  • start_url: 应用的启动 URL。

robots.txt

这个文件用于指导搜索引擎的抓取行为。它可以指定哪些页面应该被抓取或忽略，帮助你控制网站的索引和抓取。

  • User-agent: 指定对哪些搜索引擎爬虫应用规则。
  • Disallow: 指定不允许爬虫抓取的路径。
  • Allow: 指定允许爬虫抓取的路径。

docker-compose.yml

Docker Compose 配置文件用于定义多容器 Docker 应用的设置。它描述了服务、网络和卷等配置，简化了多容器应用的部署和管理。

  • services: 定义应用中的各个服务及其配置。
  • networks: 配置服务之间的网络通信。
  • volumes: 挂载数据卷以持久化数据或共享数据。

Dockerfile

Docker 配置文件定义了 Docker 镜像的构建过程，包括基础镜像、文件拷贝、命令执行和默认命令。它帮助你创建可重复的、跨环境一致的容器镜像。

  • FROM: 指定基础镜像。
  • COPY: 拷贝文件到镜像内。
  • RUN: 执行命令，如安装依赖。
  • CMD: 设置容器启动时的默认命令。

.editorconfig

EditorConfig 配置文件用于统一不同编辑器和 IDE 中的代码风格，确保团队中的代码一致性。它定义了缩进风格、字符编码、行尾字符等设置。

  • indent_style: 定义缩进风格（如 tab 或 space）。
  • indent_size: 设置缩进的大小。
  • end_of_line: 指定行尾字符（如 lf、crlf）。

.vscode/

这个目录包含 Visual Studio Code 的配置文件，如用户设置和推荐扩展。它帮助开发者在统一的开发环境中工作。

  • settings.json: 配置项目特定的 VS Code 设置。
  • extensions.json: 推荐安装的扩展列表。
  • launch.json: 配置调试设置。

.github/

GitHub 配置目录包含 GitHub Actions 和其他 GitHub 特定的配置文件。它用于自动化工作流，如 CI/CD 和代码审查。

  • workflows/: 存放 GitHub Actions 的工作流配置文件。
  • issue_templates/: 存放问题模板，用于创建一致的 issue 报告。

.husky/

Husky 配置目录包含 Git 钩子的配置文件。它允许你在 Git 提交或推送之前自动运行脚本，如 linting 和测试，确保代码质量。

  • pre-commit: 在提交之前运行的脚本，如 lint 和测试。
  • pre-push: 在推送之前运行的脚本。

sentry.properties

Sentry 配置文件用于错误跟踪和监控。它包含连接 Sentry 所需的配置，如 DSN（数据源

名称），帮助你集成错误报告系统。

  • dsn: 数据源名称，用于连接 Sentry 项目。

tsconfig.json

TypeScript 配置文件定义了 TypeScript 编译器的选项和项目的文件结构。它设置编译选项、包含和排除的文件，确保 TypeScript 代码的正确编译和类型检查。

  • compilerOptions: 设置 TypeScript 编译选项，如目标版本、模块解析等。
  • include: 指定包含在编译中的文件或目录。
  • exclude: 指定排除在编译中的文件或目录。

tailwind.config.js

Tailwind CSS 配置文件用于定义 Tailwind 的主题、插件和自定义设置。它帮助你调整 Tailwind CSS 的设计系统，添加自定义颜色、字体和其他样式设置。

  • theme: 自定义设计系统，包括颜色、字体等。
  • plugins: 添加 Tailwind 插件以扩展功能。

prettier.config.js 或 .prettierrc

Prettier 配置文件用于设置代码格式化规则。它定义了缩进、引号类型、行宽等格式化选项，确保代码的一致性和可读性。

  • tabWidth: 设置缩进的宽度。
  • singleQuote: 使用单引号而不是双引号。
  • printWidth: 设置行的最大宽度。

postcss.config.js

PostCSS 配置文件定义了 PostCSS 插件及其选项。PostCSS 用于处理 CSS，如自动添加浏览器前缀、优化 CSS 等，这个文件帮助你管理和配置 PostCSS 插件。

  • plugins: 配置使用的 PostCSS 插件，如 autoprefixer、cssnano 等。

.eslintrc.js 或 .eslintrc.json

ESLint 配置文件用于定义代码 linting 规则和选项。它帮助你维护代码质量，指定检查规则、插件和解析器，确保代码遵循最佳实践。

  • rules: 配置 linting 规则，定义代码风格和错误检查。
  • extends: 继承其他 ESLint 配置，如 Airbnb、Google 风格指南。

babel.config.js 或 .babelrc

Babel 配置文件用于定义 Babel 的编译选项和插件。Babel 用于将现代 JavaScript 代码转译为兼容旧版本浏览器的代码，这个文件帮助你配置转译规则和插件。

  • presets: 配置 Babel 的预设，如 @babel/preset-env。
  • plugins: 配置 Babel 插件，用于转译特定的 JavaScript 语法。

webpack.config.js 或 vite.config.js

Webpack 或 Vite 配置文件用于定义构建工具的设置和插件。这些文件帮助你配置模块打包、代码分割、资源处理等，优化构建过程和性能。

  • entry: 入口点，定义应用的起始文件。
  • output: 输出配置，定义打包后的文件位置和名称。
  • plugins: 使用的插件，如 HotModuleReplacementPlugin（热模块替换插件）。

rollup.config.js

Rollup 配置文件用于模块打包，特别适合库的构建。它定义了如何打包和优化模块，生成可发布的库文件。

  • input: 输入文件，定义库的入口文件。
  • output: 输出配置，定义打包后的文件位置和格式。
  • plugins: 使用的插件，如 @rollup/plugin-node-resolve 和 @rollup/plugin-commonjs。

jest.config.js

Jest 配置文件用于定义测试框架的选项和设置。Jest 是一个流行的测试框架，这个文件帮助你配置测试环境、测试覆盖率和测试文件路径。

  • preset: 配置测试预设，如 @jest/preset-env。
  • testMatch: 匹配测试文件的模式。
  • coverageDirectory: 设置覆盖率报告的输出目录。

cypress.json

Cypress 配置文件用于定义端到端测试框架的设置。Cypress 用于测试应用的交互和功能，这个文件帮助你配置测试环境和选项。

  • baseUrl: 应用的基础 URL，用于测试中的请求。
  • integrationFolder: 存放测试用例的目录。
  • supportFile: 配置支持文件的位置。

commitlint.config.js

Commitlint 配置文件用于定义提交消息的 linting 规则，确保提交消息遵循规范，如 Angular 提交规范。

  • extends: 继承标准配置，如 @commitlint/config-conventional。
  • rules: 自定义提交消息的规则。

stylelint.config.js

Stylelint 配置文件用于定义 CSS/SCSS 代码的 linting 规则，保持样式代码的质量，帮助你发现和修复样式中的问题。

  • extends: 继承标准配置，如 stylelint-config-standard。
  • rules: 自定义 CSS 规则，如缩进、选择器格式等。

.nvmrc

Node Version Manager 配置文件指定了项目中使用的 Node.js 版本。它帮助开发者和 CI 环境使用一致的 Node.js 版本，避免因版本不匹配导致的问题。

  • v14.17.0: 示例内容，指定 Node.js 的版本号。

二、常见目录和文件

public/

存放静态资源（如图片、字体）的目录。静态资源在构建过程中不会被处理，而是直接作为文件提供给客户端。

  • index.html: 主要的 HTML 文件，通常是应用的入口 HTML 页面。
  • favicon.ico: 网站的图标。

src/

存放源代码的目录，包括组件、页面、样式等。

  • index.tsx: 应用的入口文件，通常用于渲染根组件。

components/

存放 React 或 Vue 组件的目录。每个组件通常都有自己的文件夹，包含组件代码、样式和测试文件。

  • Button/: 按钮组件，可能包括 Button.tsx、Button.module.css 和 Button.test.tsx。

pages/

存放页面组件的目录（对于 Next.js）。每个文件代表一个页面，通常与路由匹配。

  • index.tsx: 应用的首页组件。
  • about.tsx: 关于页面组件。

styles/

存放样式文件的目录。包括全局样式、主题样式和 CSS 模块。

  • global.css: 全局样式文件，用于定义应用的全局样式规则。
  • theme.css: 主题样式文件，用于定义应用的主题样式。

services/

存放用于处理业务逻辑、数据获取服务。通常包含 API 请求和其他业务相关的逻辑。

  • api.ts: 封装 API 请求的方法。
  • authService.ts: 处理用户身份验证的服务。

store/

存放用于管理和存储应用状态的目录。通常包括状态管理库（如 Redux、MobX）的相关文件。

  • store.ts: 配置状态管理 store。
  • reducers/: 存放 Redux reducers 的目录。

utils/ 或 lib/

存放工具函数和辅助模块的目录。包括常用的函数和工具类，帮助简化业务逻辑。

  • formatDate.ts: 日期格式化工具函数。
  • debounce.ts: 防抖函数。

hooks/

存放自定义 hooks 的目录（如果使用 React）。自定义 hooks 用于封装和复用逻辑。

  • useFetch.ts: 自定义 hook，用于处理数据获取逻辑。
  • useLocalStorage.ts: 自定义 hook，用于与本地存储交互。

tests/

存放测试文件的目录。包含单元测试、集成测试和端到端测试的文件。

  • components/: 存放组件的测试文件。
  • pages/: 存放页面的测试文件。

docs/

存放项目文档的目录。包括开发文档、API 文档和用户手册等。

  • api.md: API 文档，描述 API 的使用和接口。
  • guide.md: 开发指南，提供项目的开发和使用说明。

scripts/

存放自定义脚本的目录。用于构建、部署和其他自动化任务。