搭建模板项目（Template Project）

在《前端工程化概述》一文，通过对前端工程化的剖析否定了前端工程化等于“搭建项目架构”的论断。但不可否认的是，项目架构是前端工程化中不可或缺的一部分。很多工程化的标准规范都需要落实到项目架构中。可以说，项目架构是前端工程化的基石。项目架构的具体体现则是模板项目（Template Project）的搭建。

认识模板项目

模板项目（Template Project）在软件开发中是一种预先设计并配置好的项目结构，它包含了启动一个新项目所需的基本组件、配置文件、代码结构以及可能的示例代码或文档。模板项目的目的是简化项目初始化过程，确保新项目从一开始就遵循最佳实践和团队的编码标准。

模板项目的所具备的特点

以下是模板项目的一些关键特征：

预配置环境：模板项目通常已经设置了项目所需的所有依赖项和工具，如编译器、构建系统、测试框架等。这些环境配置可能已经经过优化，以适应特定类型的项目或团队的工作流程。
代码结构：模板项目定义了项目的目录结构和文件命名约定。这有助于保持代码组织的一致性，并使其他开发者能够更容易地理解和导航项目。
样式指南和代码约定：模板项目可能包含编码风格指南、注释规范、命名约定等，以确保团队成员在编写代码时遵循统一的标准。
基础功能：模板项目可能包含一些预构建的基础功能，如用户认证、数据持久化、日志记录等。这些功能可以作为新项目开发的起点，并随着项目的进展进行扩展和定制。
文档和示例：模板项目通常包含详细的文档和示例代码，以帮助开发者理解如何使用模板项目，以及如何进行项目的进一步开发和维护。
可扩展性和可定制性：模板项目设计时应考虑到项目的可扩展性和可定制性。这意味着开发者可以根据项目的具体需求轻松地添加或修改功能，而不会破坏模板项目的基本结构。

分析模板项目需要具备的功能

在进行模板项目搭建前，我们需要先分析模板项目需要具备哪些功能。可以结合 SOP 和项目需求从以下几个方面考虑：

项目类型：采用哪种类型的项目，常用的项目类型有单页面应用（SPA）、多页面应用（MPA）、服务端渲染（SSR）、移动端应用、小程序等。
开发语言：支持哪些开发语言，如 JavaScript、TypeScript、React、Vue、Angular、Scss、Less 等。
构建工具：采用哪种构建工具，常用的构建工具有 Webpack、Vite、Rollup 等。
UI 框架：采用哪种 UI 框架，如 Ant Design、Element UI、Bootstrap 等。
测试框架：支持哪些测试框架，如 Jest、Mocha、Cypress、Vitest 等。
代码规范：支持哪些代码规范，如 ESLint、Prettier、Stylelint 等。
CI/CD：采用哪种 CI/CD 工具，常用的 CI/CD 工具有 GitHub Actions、GitLab CI、Jenkins 等。
部署方式：采用哪种部署方式，如 Docker、Kubernetes、AWS、GCP、Azure 等。
性能优化：支持哪些性能优化手段，如代码分割、懒加载、图片压缩、CDN 等。
安全性：支持哪些安全性措施，如 HTTPS、CSP、XSS、CSRF 等。
SEO 优化：支持哪些 SEO 优化措施，如 Sitemap、robots.txt、Meta 标签、预渲染等。
国际化：采用哪种国际化措施，如 i18n、Locale、语言切换等。
监控和日志：支持哪些监控和日志措施，如 Sentry、LogRocket、Google Analytics 等。
多环境配置：是否需要支持多环境配置。如开发环境配置、生产环境配置等。

通过上面提及的多个维度角度分析，基本可以得出模板项目的功能清单。接下来，我们需要根据这些功能清单，选择合适的工具和插件，搭建模板项目。

TIP

项目架构的考虑因素还有很多，此处只是列举了部分常见的考虑因素。具体的项目架构需要根据项目需求、团队规模、技术栈等因素综合考虑。

搭建模板项目

下面介绍如何搭建一个基于 Vue3.0 + JavaScript + Vite 的模板项目。需求清单如下：

项目架构需求清单

项目类型：单页面应用（SPA）
开发语言：Vue3.0 + JavaScript + Less + Tailwind CSS + Pinia + Vue Router + Axios
构建工具：Vite + Node + yarn
IDE：VSCode
UI 框架：Element Plus
国际化: Vue I18n
测试框架：vitest
代码规范：ESLint、Prettier、StyleLint
Git Hooks：使用 husky 实现对 commit message 的格式校验
分支管理策略：GitHub Flow
基础页面：404 页面、403 页面、500 页面
基础组件：全局布局组件、全局状态组件、全局工具组件、全局样式组件
登录模块：登录页面、登录逻辑、登录状态管理
权限管理：基于角色权限管理
性能优化：代码分割、懒加载、图片压缩（仅在项目 build 时）
CI/CD：GitHub Actions
联调跨域处理：通过 DevServer 解决跨域问题
Mock 服务器搭建：使用 axios-mock-adapter、axios、mockJs 的插件，搭建一个 Mock 服务器
Web 服务器：Nginx

初始化项目

首先，根据需求清单，初始化一个 Vue3.0 的项目。

TIP

Vue 3.0 项目的初始化说明，详见：快速上手 | Vue.js

初始化详细配置如下：

bash

Vue.js - The Progressive JavaScript Framework

√ 请输入项目名称： ... project-template
√ 是否使用 TypeScript 语法？ ... 否
√ 是否启用 JSX 支持？ ... 否
√ 是否引入 Vue Router 进行单页面应用开发？ ... 是
√ 是否引入 Pinia 用于状态管理？ ... 是
√ 是否引入 Vitest 用于单元测试？ ... 是
√ 是否要引入一款端到端（End to End）测试工具？ » 不需要
√ 是否引入 ESLint 用于代码质量检测？ » 是
√ 是否引入 Prettier 用于代码格式化？ ... 是

初始化完成后，项目目录结构如下：

bash

project-template
├── .vscode
│   ├── extensions.json
│   └── settings.json
├── node_modules
├── public
│   └── favicon.ico
├── src
│   ├── assets
│   ├── components
│   ├── App.vue
│   ├── main.js
│   ├── router
│   ├── store
│   └── views
├── .gitignore
├── index.html
├── package.json
├── ├── .editorconfig
├── ├── .prettierrc.json
├── ├── eslint.config.js
├── └── yarn.lock
├── vite.config.js
├── ├── jsconfig.json
├── └── vitest.config.js

创建 git 仓库

项目初始化完成后，我们还需要创建一个 git 仓库，将项目代码托管到 git 仓库中。

bash

git init
git add .
git commit -m "feat: init project"

接着，将项目代码推送到远程 git 仓库中。

TIP

在做这一步前，需要先在 git 仓库管理平台（如 GitHub、GitLab 等）上创建一个 git 仓库，并获取 git 仓库的 URL。

bash

git remote add origin <your-git-repo-url>
git push -u origin main

package.json 配置补充

默认生成的package.json 文件仅包含必备的配置项。为了使package.json 文件更加完善，可以补充一些配置额外的配置：

description: 增加项目描述。
author: 增加项目作者。
license: 增加项目许可证。
engines: 指定项目运行所需环境。
browserslist: 指定项目需要支持的浏览器版本。

engines 说明

engines 用于指定 Node.js 应用程序或软件包应在其上运行的 Node.js 或其他命令的版本。确保项目在指定环境下运行，以避免因为运行环境不匹配而导致的不稳定或错误。

Browserslist 说明

Browserslist 是一个在前端工具之间共享目标环境的浏览器信息的配置工具。

作用：用于指定项目需要支持的浏览器版本，从而确保前端工具（如 Autoprefixer、Stylelint、babel-preset-env 等）能够针对这些浏览器进行优化和转换。

上面配置项都为可选，可以根据项目需求进行配置。其中，engines 和 browserslist 配置项是重要的，它们可以确保项目在指定的环境下运行。

例如如下配置：

json

{
  "description": "一个 Vue3 项目模板",
  "author": "your name",
  "license": "MIT",
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=8.0.0",
    "yarn": ">=1.22.0"
  },
  "browserslist": ["default", "not dead", "not op_mini all", "not ie all"]
}

engines 和 browserslist 配置说明：

上面配置要求项目运行在 Node.js 20.0.0 及以上版本，npm v8.0.0 及以上版本, yarn 1.22.0 及以上版本，并且除了一些浏览器外需要支持 browserslist 中默认浏览器版本。

browserslist 配置详细说明：

"default"：这是一个预定义的浏览器列表，它包含了一些常见的、广泛使用的浏览器和版本。这个列表会随着 browserslist 库的更新而变化，以反映当前的浏览器市场情况。
"not dead"：这个选项排除了那些已经停止更新或不再维护的浏览器版本。所谓的“dead”浏览器是指那些不再接收安全更新或新功能的浏览器版本。
"not op_mini all"：这个选项排除了所有 Opera Mini 的版本。Opera Mini 是一款轻量级的浏览器，主要用于低性能的设备和网络环境较差的地区。由于其特殊的渲染引擎和功能限制，有时候开发者可能不希望支持这款浏览器。
"not ie all"：这个选项排除了所有版本的 Internet Explorer 浏览器。Internet Explorer 是一款老旧的浏览器，微软已于 2021 年 8 月正式停止对其的支持。现代前端开发通常不再考虑对 IE 的支持。

一些 IDE 配置

为了保证多人开发时，代码风格的一致性，我们需要添加一些项目级别的 IDE 配置。

TIP

这里以 VSCode 为例，其他 IDE 的配置类似。

调整 .editorconfig 文件

在初始化时，Vue Cli 已经自动生成了 .editorconfig 文件。这里，我们只需要调整一下文件内容即可。

默认生成的配置如下：

bash

[*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,vue}]
charset = utf-8
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

默认配置中，只对部分文件进行了配置，这里我们将其调整为对所有文件进行配置。此外，还需要将改配置文件设置为根配置文件。为了保证多系统的兼容性，这里使用 Unix 风格的换行符。调整结果如下：

bash

# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

调整 .vscode/settings.json 文件

同样的在初始化时，Vue Cli 也自动生成了 .vscode/settings.json。.vscode/settings.json是 VSCode 的配置文件。

.vscode/settings.json文件做如下调整：

申明包管理为 yarn
差异编辑器不允许忽略前后空格
取消 git 对该文件的忽略

调整后的配置如下：

json

{
  "diffEditor.ignoreTrimWhitespace": false, 
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.expand": true,
  "explorer.fileNesting.patterns": {
    "tsconfig.json": "tsconfig.*.json, env.d.ts",
    "vite.config.*": "jsconfig*, vitest.config.*, cypress.config.*, playwright.config.*",
    "package.json": "package-lock.json, pnpm*, .yarnrc*, yarn*, .eslint*, eslint*, .prettier*, prettier*, .editorconfig"
  },
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit"
  },
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "npm.packageManager": "yarn"
}

.gitignore文件做如下调整，取消.vscode/settings.json文件的忽略：

bash

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
.DS_Store
dist
dist-ssr
coverage
*.local

/cypress/videos/
/cypress/screenshots/

# Editor directories and files
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
.idea
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

*.tsbuildinfo

写在最后

目前，我们完成了模板项目的初始化，并添加了一些项目级别的 IDE 配置。接下来，我们将根据需求清单进行依赖安装配置以及模板代码编写等等工作，逐步完善模板项目。后面将以一系列的文章来一一介绍。

搭建模板项目（Template Project） ​

认识模板项目 ​

模板项目的所具备的特点 ​

分析模板项目需要具备的功能 ​

搭建模板项目 ​

初始化项目 ​

创建 git 仓库 ​

package.json 配置补充 ​

一些 IDE 配置 ​

调整 .editorconfig 文件 ​

调整 .vscode/settings.json 文件 ​

写在最后 ​

搭建模板项目（Template Project）

认识模板项目

模板项目的所具备的特点

分析模板项目需要具备的功能

搭建模板项目

初始化项目

创建 git 仓库

package.json 配置补充

一些 IDE 配置

调整 .editorconfig 文件

调整 .vscode/settings.json 文件

写在最后