模块零：项目概述、技术选型与架构蓝图

0.1 项目定义与核心学习目标

项目定义: vue3-webShop 是一个功能完备、对标企业级标准的全栈模拟电商前台应用。它涵盖了从项目初始化、用户认证、商品展示、购物车交互到订单生成的完整业务闭环。

本次实战的核心目标，并非简单地复刻功能，而是通过该项目，深入掌握构建现代化、大型、可维护前端应用的 核心能力。具体学习目标如下：

• 精通企业级 UI 解决方案: 深度掌握 Element Plus 组件库的应用，重点学习其在复杂业务场景下的使用技巧与 主题化定制 方案。
• 掌握现代状态管理架构: 学习并实践 TanStack Query (服务端状态) + Pinia (客户端状态) 的分层管理模式，彻底分离异步数据与 UI 状态，提升应用的可预测性和健壮性。
• 构建工业级工程化体系: 掌握从零开始搭建一个包含自动化代码检查、格式化、提交规范验证的完整开发环境与工作流。
• 实践可扩展的架构模式: 学习并应用“功能内聚”的目录组织方式、高内聚低耦合的组件设计原则，以及组合式函数（Composables）的最佳实践。

0.2 技术选型与分层架构设计

一个项目的技术选型，直接决定了其开发效率、性能上限和长期可维护性。我们采用了一套经过业界广泛验证的现代化技术栈，并遵循清晰的分层架构设计。

为使开发过程能完全聚焦于前端工程化，本项目将采用 json-server 来提供稳定、可预测的模拟 RESTful API。这种方式实现了彻底的前后端分离，是现代前端“接口先行”开发模式的典型实践。

0.3 项目模块化开发路线图

我们将采用模块化的方式，循序渐进地完成整个项目的开发。以下是本次实战的完整开发路线图：

1. 模块一：工程化环境搭建
   • 目标: 初始化项目，集成所有核心依赖，并建立一套完整的自动化代码质量保障体系。
2. 模块二：首页与通用布局
   • 目标: 使用 Element Plus 构建应用的整体布局，并开发包含轮播图、商品分类和推荐板块的首页。
3. 模块三：登录与用户认证
   • 目标: 实现完整的用户认证流程，精通 Element Plus 的表单校验与 TanStack Query 的 useMutation 应用。
4. 模块四：商品分类与列表
   • 目标: 开发二级分类页面，实现面包屑导航，并通过 TanStack Query 高效获取和渲染筛选后的商品列表。
5. 模块五：购物车与商品详情核心功能
   • 目标: 构建完整的购物车模块，深入实践 Pinia 与 Element Plus 复杂组件（如 Table, InputNumber）的数据联动。

模块一：专业基石 - 构筑自动化与企业级的开发环境

本模块任务清单

本模块将从零开始，构建一个功能完备、高度规范化的 Vue 3 企业级开发环境。我们将集成并深度配置所有核心依赖，建立一套全自动化的代码质量保障与提交体系。

通过以下 9 个核心任务，您将掌握构建企业级 Vue 3 开发环境的完整流程：

1.1 项目初始化

我们从最基础的一步开始：创建一个全新的项目。

1.1.1 设计思路与技术选型

在包管理器方面，我们优先选择 pnpm，而非 npm 或 yarn。pnpm 的核心优势体现在以下几个方面：

• 极致的磁盘空间效率: pnpm 采用内容寻址和硬链接技术，确保相同版本的依赖在磁盘上只存储一份，极大地节省了存储空间。
• 闪电般的安装速度: 凭借对本地缓存的优先利用，pnpm 在依赖安装速度上显著优于其竞争者。
• 严格的依赖管理: pnpm 的非扁平化 node_modules 结构从根本上解决了 “幽灵依赖” 问题，从而增强了项目的稳定性和可维护性。

在构建工具方面，Vite 是我们现代 Vue 项目开发的标准配置。其基于原生 ES 模块的开发服务器，提供了无与伦比的冷启动速度和热模块更新（HMR）性能，极大地提升了开发体验。

1.1.2 命令行操作

首先，请确保您的开发环境中已全局安装 pnpm。如果尚未安装，可以通过 npm 执行以下命令进行安装：

1

npm install -g pnpm

接下来，打开终端并导航至您的工作目录。执行以下命令来启动项目创建流程：

1

pnpm create vite

Vite 的脚手架工具将引导您完成一系列项目配置选择。请按照以下配置项进行选择：

• Project name: vue3-webShop
• Select a framework: Vue
• Select a variant: TypeScript

完成上述选择后，Vite 将在 /path/to/your/workspace/vue3-webShop 路径下完成项目骨架的搭建。随后，按照提示进入项目目录并安装所有依赖：

1
2

cd vue3-webShop
pnpm install

1.1.3 成果预览：初始项目结构

执行完以上命令后，您将获得一个纯净且标准的 Vite + Vue 3 项目结构，其目录概览如下：

1
2
3
4
5
6
7
8
9
10
11
12

# vue3-webShop/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── App.vue
│   └── main.ts
├── .gitignore
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

至此，项目的 “毛坯房” 已经搭建完毕。这是一个坚实且干净的起点，我们将在其之上，逐步添砖加瓦，构筑我们的应用大厦。

1.2 代码规范体系

在团队协作中，代码不仅是实现功能的工具，更是沟通的媒介。一套统一、自动化的代码规范体系，是保障项目长期可维护性、提升团队协作效率的基石。

1.2.1 设计思路：质量与风格的分离

在配置之前，我们必须理解两个核心工具的职责边界：

• ESLint (代码质量卫士): 它的核心职责是 发现代码中的潜在错误和不合理的写法。例如，是否存在未被使用的变量、是否在 switch 语句中缺少 break 等。它关心的是代码的 正确性 和 健壮性。
• Prettier (代码风格造型师): 它的职责非常纯粹，即 统一代码的格式。例如，是使用单引号还是双引号、行尾是否需要分号、代码行的最大宽度等。它只关心代码的 外观，不关心其逻辑。

我们的策略是让它们各司其职，并通过配置让它们完美协作：ESLint 负责修复代码质量问题，Prettier 负责最终的格式化，且 Prettier 的优先级更高，以避免两者在风格规则上的冲突。

1.2.2 核心依赖安装

现在，我们将为项目安装所有必需的 “纪律委员”。请在项目根目录下执行以下命令：

1

pnpm add -D @eslint/js eslint eslint-config-prettier eslint-plugin-vue globals prettier typescript-eslint

依赖解读:

• eslint & @eslint/js: ESLint 本体及其官方核心规则集。
• typescript-eslint: 用于让 ESLint 理解和校验 TypeScript 语法的核心插件。
• eslint-plugin-vue: 专为 .vue 单文件组件量身打造的规则插件。
• eslint-config-prettier: 关键！用于关闭所有与 Prettier 冲突的 ESLint 规则，确保 Prettier 拥有最终的格式化决定权。
• prettier: Prettier 本体。
• globals: 用于预设浏览器、Node.js 等环境的全局变量，避免 ESLint 报错。

1.2.3 现代化 ESLint 配置

ESLint 的配置已全面转向基于 ES Module 的 eslint.config.js 文件。这种新范式提供了前所未有的灵活性。

现在，我们在项目根目录创建 eslint.config.js 文件，并填入以下内容。让我们来逐块解析它的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// eslint.config.js
import globals from "globals";
import eslintJs from "@eslint/js";
import tseslint from "typescript-eslint";
import eslintPluginVue from "eslint-plugin-vue";
import eslintConfigPrettier from "eslint-config-prettier";

export default tseslint.config(
  // 全局忽略配置
  {
    ignores: ["dist", "node_modules", "*.config.js", "public", ".DS_Store"],
  },
  // 基础配置，应用于所有文件
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.es2021,
      },
    },
  },
  // ESLint 官方推荐规则
  eslintJs.configs.recommended,
  // TypeScript ESLint 推荐规则
  ...tseslint.configs.recommended,
  // Vue 插件推荐规则 (针对 Vue 3)
  ...eslintPluginVue.configs["flat/recommended"],
  // Prettier 配置，必须放在最后
  eslintConfigPrettier,
  // 自定义规则配置
  {
    files: ["**/*.vue"],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser,
      },
    },
    rules: {
      "vue/multi-word-component-names": "off",
      "vue/html-self-closing": [
        "error",
        {
          html: {
            void: "always",
            normal: "never",
            component: "always",
          },
        },
      ],
      "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
      "no-debugger": process.env.NODE_ENV === "production" ? "warn" : "off",
    },
  }
);

配置解读:

1. ignores: 全局忽略配置。我们明确告诉 ESLint 不要检查构建产物、依赖、配置文件等，以提升检查效率并避免误报。
2. languageOptions.globals: 全局变量配置。我们引入了 globals 包中预设的浏览器和 ES2021 环境的全局变量，这样在代码中使用 window、Promise 等就不会被 ESLint 判为未定义。
3. eslintJs.configs.recommended: 启用 ESLint 官方的核心推荐规则。
4. ...tseslint.configs.recommended: 启用 typescript-eslint 的推荐规则集，用于检查 TypeScript 代码。
5. ...eslintPluginVue.configs["flat/recommended"]: 启用 eslint-plugin-vue 针对 Vue 3 的推荐规则集。
6. eslintConfigPrettier: 关键步骤。此配置会禁用所有与 Prettier 格式化功能冲突的 ESLint 规则。它必须放在配置数组的靠后位置，以确保它能覆盖之前所有规则集中的样式规则。
7. 自定义规则: 这是我们项目的专属规则区。
   • files: ["**/*.vue"] 指定了这些规则仅对 .vue 文件生效。
   • parserOptions: 为 Vue 文件的 <script> 部分指定 TypeScript 解析器。
   • rules:
     • 'vue/multi-word-component-names': 'off': 关闭了组件名必须为多词的规则，在某些场景下（如根组件 App.vue）可以更灵活。
     • 'vue/html-self-closing': 配置了 HTML 元素的自闭合风格，增强代码一致性。
     • 'no-console', 'no-debugger': 设置了在生产环境下（process.env.NODE_ENV === 'production'）禁止使用 console 和 debugger，这是非常重要的生产环境最佳实践。

1.3 路径别名配置

为了在后续开发中方便地引用 src 目录下的文件，避免使用复杂的相对路径，我们需要先设置路径别名。这是后续章节正常使用 @/ 前缀的基础配置。

1.3.1 设计思路

在大型项目中，文件结构往往很深，使用相对路径会导致这样的引用：

1
2

import { apiCall } from "../../../utils/http";
import UserComponent from "../../../components/User.vue";

通过配置路径别名，我们可以将其简化为：

1
2

import { apiCall } from "@/utils/http";
import UserComponent from "@/components/User.vue";

这不仅让代码更简洁，还避免了在移动文件时需要修改引用路径的问题。

1.3.2 Vite 配置

在项目根目录的 vite.config.ts 文件中添加路径别名配置：

1
2
3
4
5
6
7
8
9
10
11
12
13

// vite.config.ts
import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

1.3.3 TypeScript 支持

为了让 TypeScript 理解这个路径别名，我们需要更新 TypeScript 配置。

方法一：如果您的项目使用单一 tsconfig.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
}

方法二：如果您的项目使用 tsconfig.app.json (推荐)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// tsconfig.app.json
{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    /* 路径别名配置 */
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
}

1.3.4 功能测试

配置完成后，在任意 Vue 组件中尝试使用 @/ 前缀：

1
2
3
4
5
6
7
8
9
10

<script setup lang="ts">
// 测试路径别名是否生效
import { ref } from "vue";
// 假设后续章节会创建这个文件
// import { someUtil } from '@/utils/helpers'
</script>

<template>
  <div>路径别名配置完成</div>
</template>

如果 VS Code 能够正确提供路径提示和自动补全，说明配置成功。

1.4 UI 组件库与图标库集成

为项目引入一套成熟的 UI 组件库，是现代前端开发的标准实践。它能极大提升开发效率，保证 UI 的一致性和可访问性，让我们能专注于业务逻辑的实现。

1.4.1 设计思路：按需自动导入

在项目中引入 Element Plus 有两种方式：全局引入和按需导入。

• 全局引入: 简单直接，但会将所有组件和图标打包，导致最终构建产物体积过大。
• 按需导入: 只打包代码中实际使用到的组件，是生产环境的最佳实践。

为了实现优雅的按需导入，避免在每个文件中手动 import { ElButton } from 'element-plus' 和 import { Edit } from '@element-plus/icons-vue'，我们借助 unplugin 系列插件来自动化这一过程。

1.4.2 核心依赖安装

我们将安装 element-plus 本体、其官方图标库，以及三个实现自动导入的 unplugin 插件。请在项目根目录下执行以下命令：

1
2
3
4
5

# 1. 安装 element-plus 和图标库
pnpm add element-plus @element-plus/icons-vue

# 2. 安装 unplugin 系列插件
pnpm add -D unplugin-vue-components unplugin-auto-import unplugin-icons @iconify-json/ep

依赖解读:

1.4.3 Vite 配置文件 (vite.config.ts)

安装完依赖后，我们需要在 vite.config.ts 中启用并配置这些插件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// vite.config.ts
import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// 1. 引入所需插件
import AutoImport from "unplugin-auto-import/vite";
import Components from "unplugin-vue-components/vite";
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";

// 引入 unplugin-icons
import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";

export default defineConfig({
  plugins: [
    vue(),
    // 2. 配置 unplugin-auto-import
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    // 3. 配置 unplugin-vue-components
    Components({
      resolvers: [
        // 自动导入 Element Plus 组件
        ElementPlusResolver({ importStyle: "sass" }),
        // 自动导入 Element Plus 图标
        // 我们约定图标组件的使用方式是 <i-ep-iconName />
        IconsResolver({
          prefix: "i", // 默认为 i, 可不写
          enabledCollections: ["ep"], // ep 是 element-plus 的图标库
        }),
      ],
    }),
    // 4. 配置 unplugin-icons
    Icons({
      autoInstall: true,
    }),
  ],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

配置解读:

• IconsResolver: 这是专门用于解析图标的解析器。
  • enabledCollections: ['ep']: 告诉解析器只启用 Element Plus 的图标集 (ep 是其简称)。
• 使用约定: 我们建立了一个清晰的图标使用约定：所有以 <i-ep- 开头的标签（例如 <i-ep-edit />），都会被自动识别为 Element Plus 的图标并导入。

1.4.4 TypeScript 类型支持 (Volar)

为了让 TypeScript 和 Volar 能够识别自动导入的组件和图标，我们需要确保 tsconfig.json 的 include 配置包含了插件自动生成的类型声明文件。

1
2
3
4
5
6
7
8
9
10
11
12
13

// tsconfig.json
{
  // ...
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "auto-imports.d.ts",
    "components.d.ts"
  ]
  // ...
}

1.4.5 功能测试

配置完成后，我们来验证组件和图标是否都已成功集成。打开 src/App.vue 文件，替换为以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<script setup lang="ts"></script>

<template>
  <el-button type="primary">我是按钮</el-button>

  <el-button type="success">
    <i-ep-edit />
    编辑按钮
  </el-button>

  <div>
    <i-ep-success color="green" style="font-size: 2em" />
    <i-ep-warning color="orange" style="font-size: 2em" />
    <i-ep-circle-close color="red" style="font-size: 2em" />
  </div>
</template>

现在，启动开发服务器 (pnpm run dev)。如果你能看到按钮和图标都正常显示，那么恭喜你，自动导入已成功配置！

1.4.6 深度解析：图标的两种用法 (手动 vs 自动)

你可能会有疑问：为什么我们不使用官方文档中常见的 import { Edit } from '@element-plus/icons-vue' 方式，而是用 <i-ep-edit />？这是一个非常好的问题，理解它有助于你掌握现代前端的工程化思想。

方法 A: 手动导入 (传统方式)

这是 Element Plus 官方文档中最常见的用法，依赖关系清晰。

• 代码示例:

  1 2 3 4 5 6

  <script setup lang="ts"> import { Phone } from "@element-plus/icons-vue"; </script> <template> <el-link :icon="Phone">在线客服</el-link> </template>

• 优点: 依赖关系明确，无需额外配置。
• 缺点: 当使用大量图标时，<script> 部分会变得非常冗长。

方法 B: 自动导入 (工程化实践)

这是我们通过插件配置实现的用法，开发体验极致高效。

• 代码示例:

  1 2 3 4

  <template> <!-- 无需在 script 中做任何事 --> <el-button type="success"> <i-ep-edit /> 编辑按钮 </el-button> </template>

• 优点: <script> 保持干净，开发效率极高，代码更整洁。
• 缺点: 需要前期配置，对于不熟悉配置的人来说有 “魔法” 成分。

结论：
在本教程中，我们将 优先使用自动导入 的方式，因为它极大地提升了开发体验，是构建大型企业级项目的首选。理解这两种方式的差异，将让你对现代前端工具链有更深刻的认识。

1.5 国际化 (i18n) 配置

Element Plus 组件库默认的语言是英语。对于面向中文用户的项目，我们需要进行国际化配置，将提示文字、日期格式等转换为中文，以提供符合用户习惯的体验。

1.5.1 设计思路

Element Plus 提供了两种主流的国际化配置方案：

1. 全局配置: 在应用入口文件 (main.ts) 中，通过 app.use 传入全局配置对象。这是最常用、最直接的方式，一次配置，全局生效。
2. ElConfigProvider 组件: 使用 ElConfigProvider 组件包裹根组件或部分组件树，可以实现全局或局部的语言配置。

对于我们整个应用都需要使用中文的场景，全局配置 是最佳选择。

1.5.2 全局配置实现

我们将修改 main.ts 文件，导入 Element Plus 的中文语言包并进行全局注册。

现在，让我们整合这段逻辑到 main.ts 文件中。如果架构师的 main.ts 中已经有 app.use(ElementPlus)，请将其替换为带有配置对象的版本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// src/main.ts

import { createApp } from "vue";
import App from "./App.vue";

import ElementPlus from "element-plus";
// 1. 导入 Element Plus 的 CSS 样式文件
import "element-plus/dist/index.css";
// 2. 导入 Element Plus 的中文语言包
// 注意：新版本 Element Plus 的语言包路径可能有所变化，请以实际为准
// .mjs 后缀表示这是一个 ES Module
import zhCn from "element-plus/es/locale/lang/zh-cn";

const app = createApp(App);

// 3. 全局注册 Element Plus 并配置国际化
app.use(ElementPlus, {
  locale: zhCn,
});

app.mount("#app");

配置解读:

• 我们从 element-plus/dist/locale/ 目录下导入了 zh-cn.mjs，这是一个包含了所有组件中文翻译的对象。
• 在调用 app.use(ElementPlus) 时，我们传入了第二个参数，一个配置对象 { locale: zhCn }。Element Plus 内部会接收这个对象，并将 zhCn 设为默认语言包。

1.5.3 功能测试

如何验证国际化配置是否生效？我们可以使用一个包含大量文本的组件，例如日期选择器 (ElDatePicker)。

修改 src/App.vue 进行测试：

1
2
3
4
5
6
7
8
9
10
11

<template>
  <div class="test-container">
    <el-date-picker type="date" placeholder="请选择日期" />
  </div>
</template>

<style scoped>
  .test-container {
    padding: 20px;
  }
</style>

现在，运行项目。当你点击日期选择框时，弹出的面板中的 “一月”、“周一”、“今天” 等文字如果都显示为中文，则证明我们的国际化配置已成功生效。

现在，运行项目。当你点击日期选择框时，弹出的面板中的 “一月”、“周一”、“今天” 等文字如果都显示为中文，则证明我们的国际化配置已成功生效。

1.6 SCSS 企业级架构与主题定制

在企业级项目中，样式的可维护性、可扩展性和一致性至关重要。本节，我们将摒弃零散的样式文件，构建一套专业、分层的 SCSS 架构。我们将学习如何集成并定制 Element Plus，同时建立一套包含全局变量、基础规范、混入（Mixins）的完整体系，并通过一个统一的入口文件进行管理，最终由 Vite 实现高效的全局注入。

1.6.1 设计思路：全局样式与编译工具的分离

一个顶级的样式架构必须清晰地分离两个概念：

1. 全局样式表 (Global Stylesheet): 这是应用的基础外观，包含 CSS 重置、基础排版 (body, a 标签等) 和 Element Plus 的定制化样式。这些样式应该被编译成一个单一的 CSS 文件，并在应用入口 (main.ts) 加载且仅加载一次。
2. 编译时工具 (Compile-Time Tools): 这是我们在编写组件独有样式时需要的设计令牌和代码片段，如 $GLColor 变量和 flex-center 混入。这些工具本身不产生 CSS，它们需要在 每个组件的 <style> 块中都可用，以便我们遵循设计规范。

我们将通过 main.scss 文件来组织 全局样式表，并通过 Vite 的 additionalData 配置来全局提供 编译时工具。

1.6.2 依赖安装与文件结构创建

1. 安装 SCSS 编译器与重置库:

   1	pnpm add -D sass scss-reset

2. 创建全新的样式文件结构:
   在 src/ 目录下创建 styles 文件夹，并建立以下专业结构：

   1 2 3 4 5 6 7 8 9 10 11

   src/ └── styles/ ├── abstracts/ │ ├── _variables.scss # 全局变量 │ ├── _mixins.scss # 全局混入 │ └── _utilities.scss # 工具类 ├── base/ │ └── _index.scss # 基础样式规范 ├── element/ │ └── _index.scss # Element Plus 变量覆盖 └── main.scss # 唯一的全局样式总入口

1.6.3 编写抽象层 (Abstracts)

这是我们的 “工具箱”，包含所有不直接输出 CSS 的变量和混入。

1. _variables.scss

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/styles/abstracts/_variables.scss

// 品牌色
$GLColor: #0155b2;

// 功能色
$sucColor: #1dc779;
$warnColor: #ffb302;
$priceColor: #cf4444; // 也用于危险/错误状态
$helpColor: #e26237;

// 中性色
$textColor: #333;
$textColor-secondary: #666;
$borderColor: #e4e4e4;
$bgColor: #f5f5f5;

// 其他
$borderRadius: 4px;
$transition-duration: 0.2s;

2. _mixins.scss

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/styles/abstracts/_mixins.scss

// Flexbox 快速居中
@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

// 文本溢出截断
@mixin truncate-text {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

3. _utilities.scss

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// src/styles/abstracts/_utilities.scss

// 工具类混入
@mixin utilities {
  .text-center {
    text-align: center;
  }

  .text-left {
    text-align: left;
  }

  .text-right {
    text-align: right;
  }
}

1.6.4 编写会输出 CSS 的样式层

这两个层级的文件会实际产出 CSS，它们需要显式地导入自己所依赖的变量。

1. base/_index.scss

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// src/styles/base/_index.scss

// 导入变量
@use "../abstracts/variables" as *;

// 1. 根设置: 设定 rem 计算基准和全局盒模型
html {
  font-size: 62.5%; // 1rem = 10px
  box-sizing: border-box;
}

*,
*::before,
*::after {
  box-sizing: inherit;
}

// 2. Body 基础排版
body {
  font-size: 1.6rem; // 默认 16px
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  line-height: 1.5;
  color: $textColor;
  background-color: $bgColor;
  -webkit-font-smoothing: antialiased;
}

// 3. 基础链接规范
a {
  color: $GLColor;
  text-decoration: none;
  transition: color $transition-duration;
  &:hover {
    color: lighten($GLColor, 10%);
  }
}

2. element/_index.scss

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// src/styles/element/_index.scss

// 显式导入依赖的变量
@use "../abstracts/variables" as *;

@forward "element-plus/theme-chalk/src/common/var.scss" with (
  $colors: (
    "primary": (
      "base": $GLColor,
    ),
    "success": (
      "base": $sucColor,
    ),
    "warning": (
      "base": $warnColor,
    ),
    "danger": (
      "base": $priceColor,
    ),
    "error": (
      "base": $priceColor,
    ),
  )
);

1.6.5 编写全局样式入口 main.scss

此文件是 全局样式表的指挥中心，它按顺序编排所有会产出 CSS 的样式模块。

1
2
3
4
5
6
7
8
9
10

// src/styles/main.scss

// 1. 第三方库: 如样式重置库
@use "scss-reset";

// 2. 基础层: HTML 元素的全局样式
@use "base";

// 3. 框架覆盖层: 对 Element Plus 的样式定制
@use "element";

1.6.6 理解工作流：最佳注入策略

1.6.7 实施最终配置

现在，我们将整合所有配置，实施我们讨论出的最佳注入策略。

1. 更新 vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

// vite.config.ts
import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// 1. 引入所需插件
import AutoImport from "unplugin-auto-import/vite";
import Components from "unplugin-vue-components/vite";
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";

// 引入 unplugin-icons
import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";

export default defineConfig({
  plugins: [
    vue(),
    // 2. 配置 unplugin-auto-import
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    // 3. 配置 unplugin-vue-components
    Components({
      resolvers: [
        // 1. 配置 ElementPlusResolver，指定 importStyle 为 sass
        ElementPlusResolver({ importStyle: "sass" }),
        // 自动导入 Element Plus 图标
        IconsResolver({
          prefix: "i", // 默认为 i, 可不写
          enabledCollections: ["ep"], // ep 是 element-plus 的图标库
        }),
      ],
    }),
    // 4. 配置 unplugin-icons
    Icons({
      autoInstall: true,
    }),
  ],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
  // 2. SCSS 自动化注入配置
  css: {
    preprocessorOptions: {
      scss: {
        // 只注入变量和 mixins，避免重复导入 CSS 输出
        additionalData: `
          @use "@/styles/abstracts/variables" as *;
          @use "@/styles/abstracts/mixins" as *;
          @use "@/styles/abstracts/utilities" as *;
        `,
      },
    },
  },
});

2. 更新 main.ts

1
2
3
4
5
6
7
8
9
10
11
12

// src/main.ts
import { createApp } from "vue";
import App from "./App.vue";
import ElementPlus from "element-plus";
import zhCn from "element-plus/es/locale/lang/zh-cn";

// 核心：导入唯一的全局样式文件
import "@/styles/main.scss";

const app = createApp(App);
app.use(ElementPlus, { locale: zhCn });
app.mount("#app");

1.6.8 清理与测试

1. 确认 main.ts: 确保 import 'element-plus/dist/index.css' 已被彻底删除，因为我们的样式体系已经完美接管。

2. 功能测试: 重启 Vite 开发服务器。

   • 全局样式: 页面基础排版（字体、背景色等）应已正确应用。这证明 main.scss 已被成功加载一次。
   • Element Plus 定制: <el-button type="primary"> 按钮应显示为我们定义的 $GLColor。
   • 组件内工具: 在任意 Vue 组件的 <style lang="scss"> 块中，你都可以直接使用 $GLColor 变量或 @include flex-center; 混入来编写该组件的 独有样式，而无需任何手动导入。

通过这套架构，我们实现了企业级项目的终极目标：一套清晰、高效、可维护的样式体系，它完美平衡了全局一致性与组件独立性。

1.7 核心服务集成

一个应用不仅需要美观的 UI，还需要强大的 “内脏” 来处理数据请求、页面导航和状态管理。本节将为我们的项目集成这些核心服务，搭建起应用的 “神经与循环系统”。

1.7.1 网络请求层 (Axios) 封装

在任何项目中，直接在组件中调用 axios.get(...) 都是一种不良实践。我们需要一个统一的、可配置的封装层来处理通用逻辑。

• 设计思路: 我们将创建一个 axios 实例，并配置通用的 baseURL 和 timeout。更重要的是，我们将利用 拦截器 (Interceptors) 来实现：
  1. 请求拦截器: 未来用于统一注入用户 token。
  2. 响应拦截器: 用于统一处理返回数据的结构（例如，直接返回 res.data）和集中的错误处理（例如，401 未授权拦截）。

1. 依赖安装

1

pnpm add axios

2. 封装 HTTP 工具模块

在 src/utils/ 目录下创建 http.ts 文件。

请将以下代码填入 src/utils/http.ts 文件中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// src/utils/http.ts
import axios from "axios";

const httpInstance = axios.create({
  baseURL: "http://localhost:3001",
  timeout: 5000,
});

// axios 请求拦截器
httpInstance.interceptors.request.use(
  (config) => {
    // 1. 从 pinia 获取 token 数据
    // 2. 按照后端的要求拼接 token 数据
    return config;
  },
  (e) => Promise.reject(e)
);

// axios 响应式拦截器
httpInstance.interceptors.response.use(
  // 剥离了一层 data，后续直接拿到的就是响应 data
  (res) => res.data,
  (e) => {
    // 1. 统一错误提示
    // 2. 401 token 失效处理
    return Promise.reject(e);
  }
);

export default httpInstance;

代码解读:

• axios.create: 创建一个独立的 axios 实例，避免污染全局 axios。
• interceptors.request: 在请求发送前进行拦截。我们在这里预留了未来添加 token 的逻辑。
• interceptors.response: 在响应到达 then/catch 之前进行拦截。我们在这里做了两件重要的事：
  1. 成功回调中 res => res.data，这可以让我们在后续调用时直接获取数据，无需再 response.data。
  2. 失败回调中预留了统一错误处理逻辑，例如 token 失效后的跳转登录页。

1.7.2 路由系统 (Vue Router)

Vue Router 是 Vue 官方的路由管理器，是构建单页应用 (SPA) 的标准配置。

1. 依赖安装

1

pnpm add vue-router

2. 创建路由配置文件

在 src/ 目录下创建 router/index.ts 文件。

请将以下代码填入 src/router/index.ts 文件中，并根据需要创建对应的 .vue 文件 (可以先只写一个 <template><div>...</div></template>)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// src/router/index.ts
import { createRouter, createWebHistory } from "vue-router";
import Layout from "@/views/Layout/index.vue";
import Login from "@/views/Login/index.vue";

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: "/",
      component: Layout,
      children: [
        {
          path: "", // 默认二级路由
          component: () => import("@/views/Home/index.vue"),
        },
        {
          path: "category/:id", // 使用 path parameter 接收 id
          component: () => import("@/views/Category/index.vue"),
        },
      ],
    },
    {
      path: "/login",
      component: Login,
    },
  ],
});

export default router;

代码解读:

• createWebHistory: 使用 H5 History 模式，URL 路径更美观。
• routes: 路由规则数组。我们定义了一个 嵌套路由：
  • / 路径会渲染 Layout 组件，它作为所有一级页面的通用布局（包含导航、页头、页脚）。
  • children 数组定义了二级路由。当访问 / 时，由于 path: ''，会默认在 Layout 组件的 <RouterView /> 中渲染 Home 组件。

1.7.3 状态管理引擎安装与最终注册

最后，我们安装 Pinia 和 TanStack Query，并在 main.ts 中完成所有核心服务的最终注册。

1. 依赖安装

1
2

pnpm add pinia @tanstack/vue-query
pnpm add pinia-plugin-persistedstate

2. 在 main.ts 中完成所有服务注册

这是我们 main.ts 文件的最终形态，它成为了所有核心服务的 “总装车间”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/main.ts
import { createApp } from "vue";
import App from "./App.vue";
import router from "./router"; // 导入路由
import { createPinia } from "pinia";
import { VueQueryPlugin } from "@tanstack/vue-query";
import ElementPlus from "element-plus";
import piniaPluginPersistedstate from "pinia-plugin-persistedstate"; // 1. 导入插件
import zhCn from "element-plus/es/locale/lang/zh-cn";

// 核心：导入唯一的全局样式文件
import "@/styles/main.scss";

const app = createApp(App);
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate); // 2. 注册插件
app.use(pinia);
app.use(router); // 注册路由
app.use(VueQueryPlugin); // 注册 TanStack Query

app.use(ElementPlus, {
  locale: zhCn,
});

app.mount("#app");

1.8 API 自动导入优化

在【任务 1.3】中，我们已经为项目配置了路径别名，解决了深层相对路径的问题。本节，我们将解决另一个影响开发效率的痛点：在每个 Vue 组件中重复编写 import { ref, computed, ... } from 'vue'。

1.8.1 设计思路：解放 import 语句

unplugin-auto-import 插件的原理是在编译时扫描代码，如果发现你使用了像 ref, computed, onMounted 等未被导入的变量，它会自动检查这些变量是否属于预设库（如 ‘vue’, ‘vue-router’）的导出成员。如果是，它会自动为架构师添加导入语句。为了让 TypeScript 理解这些 “凭空出现” 的全局变量，该插件还会生成一个类型声明文件（.d.ts）。

1.8.2 Vite 配置文件 (vite.config.ts)

我们将扩展 unplugin-auto-import 的配置，明确告知它需要为哪些库开启自动导入。

现在，让我们扩展 vite.config.ts 中 unplugin-auto-import 的配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// vite.config.ts
// ... imports
import AutoImport from "unplugin-auto-import/vite";
// ...

export default defineConfig({
  plugins: [
    vue(),
    // 扩展 unplugin-auto-import 配置
    AutoImport({
      // 1. 指定需要自动导入的库
      imports: ["vue", "vue-router"],
      // 2. 指定生成 d.ts 文件的位置
      dts: "src/auto-imports.d.ts",
      // 3. 配置 ElementPlusResolver
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      // ... existing config
    }),
    // ... other plugins
  ],
  // ... resolve and css config
});

配置解读:

• imports: ['vue', 'vue-router']: 我们明确告诉插件，自动扫描并导入 vue 和 vue-router 这两个库导出的所有 API。
• dts: 'src/auto-imports.d.ts': 这是至关重要的一步。插件会创建一个 auto-imports.d.ts 文件，其中包含了所有自动导入 API 的 TypeScript 类型声明。

1.8.3 TypeScript 类型支持

我们需要确保 TypeScript 配置文件能够识别这个自动生成的类型声明文件。

在 tsconfig.app.json 文件中，确保 include 数组包含了 auto-imports.d.ts：

1
2
3
4
5
6
7
8
9
10
11
12

// tsconfig.app.json
{
  // ... existing config
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "auto-imports.d.ts",
    "components.d.ts"
  ]
}

1.8.4 功能测试

现在，让我们创建一个测试组件来验证自动导入是否正常工作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<!-- src/components/AutoImportTest.vue -->
<script setup lang="ts">
// 注意：我们没有手动导入任何东西！
const count = ref(0);
const doubleCount = computed(() => count.value * 2);
const router = useRouter();

const increment = () => {
  count.value++;
};

const goHome = () => {
  router.push("/");
};

onMounted(() => {
  console.log("组件已挂载，自动导入测试成功！");
});
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double Count: {{ doubleCount }}</p>
    <el-button @click="increment">增加</el-button>
    <el-button @click="goHome">回到首页</el-button>
  </div>
</template>

重启 Vite 开发服务器后，如果上述代码能够正常运行且 VS Code 提供了完整的类型提示，说明自动导入配置成功！

最终完整的 vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

// vite.config.ts
import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// 1. 引入所需插件
import AutoImport from "unplugin-auto-import/vite";
import Components from "unplugin-vue-components/vite";
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";

// 引入 unplugin-icons
import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";

export default defineConfig({
  plugins: [
    vue(),
    // 2. 配置 unplugin-auto-import
    AutoImport({
      // 1. 指定需要自动导入的库
      imports: ["vue", "vue-router"],
      // 2. 指定生成 d.ts 文件的位置
      dts: "src/auto-imports.d.ts",
      // 3. 配置 ElementPlusResolver
      resolvers: [ElementPlusResolver()],
    }),
    // 3. 配置 unplugin-vue-components
    Components({
      resolvers: [
        // 自动导入 Element Plus 组件
        ElementPlusResolver({ importStyle: "sass" }),
        // 自动导入 Element Plus 图标
        // 我们约定图标组件的使用方式是 <i-ep-iconName />
        IconsResolver({
          prefix: "i", // 默认为 i, 可不写
          enabledCollections: ["ep"], // ep 是 element-plus 的图标库
        }),
      ],
    }),
    // 4. 配置 unplugin-icons
    Icons({
      autoInstall: true,
    }),
  ],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },

  server: {
    proxy: {
      // 代理 API 请求到 Mock 服务器
      "/api": {
        target: "http://localhost:3001",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ""),
      },
      // 代理图片资源到 Mock 服务器
      "/images": {
        target: "http://localhost:3001",
        changeOrigin: true,
      },
    },
  },
  // 2. SCSS 自动化注入配置
  css: {
    preprocessorOptions: {
      scss: {
        // 只注入变量和 mixins，避免重复导入 CSS 输出
        additionalData: `
          @use "@/styles/abstracts/variables" as *;
          @use "@/styles/abstracts/mixins" as *;
          @use "@/styles/abstracts/utilities" as *;
        `,
      },
    },
  },
});

1.9 自动化提交流程

IDE 级别的配置能提升个人效率，但无法保证团队协作的一致性。我们需要在代码流入版本库的最后一道关卡——git commit——设立 “自动化哨兵”，强制所有提交都遵循统一的质量和规范标准，确保代码仓库的纯净与专业。

1.9.1 设计思路：三道防线

我们将建立三道质量防线：

1. 第一道防线 - 预提交检查 (pre-commit Hook): 在 git commit 执行前，自动对暂存区的文件运行 ESLint 和 Prettier，确保所有即将提交的代码都符合质量和风格标准。
2. 第二道防线 - 提交信息校验 (commit-msg Hook): 校验提交信息是否遵循约定式提交规范，确保提交历史的专业性和可读性。
3. 第三道防线 - 推送前检查: 在推送到远程仓库前，可以添加额外的检查，如运行完整的测试套件。

1.9.2 Git 仓库初始化与远程连接

首先，我们需要为项目创建 Git 仓库并连接到远程仓库：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 初始化 Git 仓库
git init

# 2. 添加所有文件到暂存区
git add .

# 3. 创建初始提交
git commit -m "feat: initial project setup with Vue 3 + TypeScript"

# 4. 连接到远程 GitHub 仓库（请替换为你的仓库地址）
git remote add origin https://github.com/your-username/vue3-webshop.git

# 5. 推送到远程仓库
git push -u origin main

1.9.3 依赖安装

现在安装所有自动化工具：

1

pnpm add -D husky lint-staged @commitlint/cli @commitlint/config-conventional

依赖解读:

1.9.4 配置 Husky 与 lint-staged (代码检查)

1. 初始化 Husky:

   1	pnpm exec husky init

2. 配置 lint-staged:
   在 package.json 中添加 lint-staged 配置：

   1 2 3 4 5 6 7 8

   // package.json { // ... existing config "lint-staged": { "*.{js,jsx,ts,tsx,vue}": ["eslint --fix --cache", "prettier --write"], "*.{json,md,scss,css}": ["prettier --write"] } }

3. 创建预提交钩子:
   修改 .husky/pre-commit 文件：

   1 2	# .husky/pre-commit npx lint-staged

工作原理解读:

• lint-staged 只会对 Git 暂存区（git add 后的文件）执行检查，大大提升了性能。
• 对于 JS/TS/Vue 文件，先运行 eslint --fix 自动修复问题，再用 prettier 统一格式。
• 对于配置文件和文档，只运行 prettier 格式化。

1.9.5 配置 commitlint (提交信息规范)

1. 约定式提交规范说明:
   我们要求所有提交信息都遵循 type(scope): subject 的格式。这不仅使提交历史清晰可读，更是自动化生成 CHANGELOG 和版本管理的基础。

   类型 (type)	含义
   feat	新增功能
   fix	修复 Bug
   docs	文档变更
   style	代码风格调整（不影响逻辑）
   refactor	代码重构
   perf	性能优化
   test	新增或修改测试
   chore	构建流程、辅助工具的变更

2. 创建 commitlint.config.js:
   在项目根目录创建配置文件：

   1 2 3 4

   // commitlint.config.js export default { extends: ["@commitlint/config-conventional"], };

3. 创建提交信息钩子:
   创建 .husky/commit-msg 文件：

   1 2	# .husky/commit-msg npx --no-install commitlint --edit $1

1.9.6 添加便捷脚本

为了方便开发，在 package.json 中添加一些实用的脚本：

1
2
3
4
5
6
7
8
9
10
11

// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint . --fix",
    "lint:check": "eslint .",
    "format": "prettier --write ."
  }
}

1.9.7 完整测试流程

现在让我们测试整个自动化工作流是否正常：

1. 故意制造一些格式问题: 在任意 .vue 文件中添加一些不规范的代码（如缺少分号、不一致的引号等）。

2. 测试预提交检查:

   1 2	git add . git commit -m "test commit"

   你应该看到 lint-staged 自动运行，修复代码格式问题。

3. 测试提交信息校验:

   执行一次 不符合规范 的提交：git commit -m "test"。

   • 预期结果: 终端会提示 subject may not be empty, type may not be empty 等错误，提交被 中止。

   执行一次 符合规范 的提交：git commit -m "feat: setup automated commit workflow"。

   • 预期结果:
     lint-staged 首先运行，你会看到 eslint 和 prettier 的输出，格式问题被自动修复。
     commitlint 校验通过。提交成功！

模块二：通用布局与首页开发

本模块任务清单

产品经理 Amy 走到了我们的工位前：“项目的第一阶段目标很明确：我们要先搭建起整个应用的‘骨架’——也就是通用的头部和底部，然后集中精力打造一个能立刻吸引用户眼球的首页。”
UI 设计师 Leo 紧接着在 Figma 中展示了他的最终设计稿：
“这是首页的视觉稿，包含了响应式的导航栏、全屏的轮播图，以及一个非对称布局的人气推荐板块。所有组件的间距、颜色和字体都已经标注好了。”
现在，需求已经明确，设计稿也已就绪。作为前端开发者，我们的任务就是将这些静态的设计稿，转化为一个动态的、数据驱动的、交互丰富的真实网页。

本模块将从零开始，完成整个应用的通用布局框架（导航、头部、底部），并开发功能丰富、数据驱动的电商首页。在本模块中，我们将直接应用 Element Plus 核心组件来高效构建 UI，首次深度实践 Pinia 进行全局状态管理，并使用 TanStack Query 以现代化的方式获取首页业务数据。

1. 任务 2.1: 静态布局骨架搭建
2. 任务 2.2: 静态顶部通栏 (LayoutNav) 开发
3. 任务 2.3: Pinia 实战 - 动态化顶部通栏
4. 任务 2.4: 静态站点头部 (LayoutHeader) 开发
5. 任务 2.5: Pinia 实战 - 动态渲染头部导航
6. 任务 2.6: 静态站点底部 (LayoutFooter) 开发
7. 任务 2.7: TanStack Query 实战 - 首页轮播图 (HomeBanner) 开发
8. 任务 2.8: 首页-人气推荐 (HomeHotProduct) 板块开发

2.1 静态布局骨架搭建

一个大型应用的许多页面都共享着相同的外部框架，例如页头、页脚等。我们将这些公共部分抽离成一个 Layout 组件，其他页面作为其子路由嵌套在其中。这遵循了 DRY (Don't Repeat Yourself) 原则，是组件化开发的核心思想。

2.1.1 设计思路：组件化与语义化

我们在【模块一】的路由配置中，已经将 / 路径指向了 Layout 组件，并将 Home 等页面作为其子路由。现在，我们的任务就是构建 Layout 这个父级容器。

通过分析设计图，我们可以认为 Layout/index.vue 的职责是组合 LayoutNav、LayoutHeader、LayoutFooter 和 <RouterView />。为了让这个组合的结构更加清晰和专业，我们将使用 Element Plus 提供的布局容器组件：

• <el-container>: 外层容器。
• <el-header>: 顶部容器，我们将在这里放置 LayoutNav 和 LayoutHeader。
• <el-main>: 主要区域容器，用于包裹 <RouterView />，这是所有子路由组件将被渲染的地方。
• <el-footer>: 底部容器，用于放置 LayoutFooter。

使用这些语义化的标签，能让代码的可读性和可维护性大大增强。

2.1.2 编码实现

首先，我们需要在 src/views/Layout/ 目录下创建 index.vue 文件，以及其子组件目录 components/ 和其中的三个文件 LayoutNav.vue, LayoutHeader.vue, LayoutFooter.vue。（为保证流程，子组件暂时留空即可）

现在，我们来编写 src/views/Layout/index.vue 的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<script setup>
import LayoutNav from './components/LayoutNav.vue'
import LayoutHeader from './components/LayoutHeader.vue'
import LayoutFooter from './components/LayoutFooter.vue'
</script>

<template>
  <el-container>
    <el-header>
      <LayoutNav />
      <LayoutHeader />
    </el-header>
    <el-main>
      <RouterView />
    </el-main>
    <el-footer>
      <LayoutFooter />
    </el-footer>
  </el-container>
</template>

<style lang="scss" scoped>
// 为 el-main 设置最小高度，确保页脚在内容不足时也能置底
.el-main {
  min-height: calc(100vh - 281px); // 281px 是页头和页脚的大致总高度
}

// 移除 el-header 和 el-footer 的默认 padding
.el-header,
.el-footer {
  padding: 0;
  height: auto;
}
</style>

我们如何能在不修改 App.vue 的情况下，看到我们开发的 LayoutNav 组件？这需要我们理解 Vue Router 的核心工作流：

1. 应用入口 (main.js): 我们的应用从 main.js 启动，在这一步，我们 createApp(App) 并 app.use(router)。这使得整个应用具备了路由能力。
2. 根组件 (App.vue): App.vue 是所有视图的根容器，它的模板中只有一个核心内容：<RouterView />。这是一个占位符，告诉 Vue Router：“所有匹配到的路由组件都在这里渲染”。
3. 路由配置 (router/index.js): 我们的路由表 routes 数组中，配置了 path: '/' 对应的组件是 Layout 组件。
4. 布局组件 (Layout/index.vue): 当我们访问根路径 / 时，Layout 组件就会被渲染到 App.vue 的 <RouterView /> 中。而 Layout 组件内部又包含了 LayoutNav 组件。

结论: main.js -> App.vue -> RouterView -> (URL: '/') -> Layout.vue -> LayoutNav.vue。正是这条清晰的渲染链路，保证了我们接下来开发的每一个 Layout 子组件，都能够 在访问首页时被立刻看到。

文件路径: src/app.vue

1
2
3
4
5
6
7

<script setup lang="ts">

</script>

<template>
  <router-view />
</template>

2.2 静态顶部通栏 (LayoutNav) 开发

顶部通栏是位于页面最顶部的导航区域，通常包含用户的登录状态、快捷链接等。我们首先来开发它的静态结构和样式，即组件的“骨架”与“皮肤”。

2.2.1 设计思路：状态分离

一个健壮的组件应该能够清晰地展示其不同状态下的视图。对于顶部通栏，核心的状态有两个：登录状态 和 未登录状态。

在这一步，我们先不关心状态如何切换，而是把两种状态下的 DOM 结构都完整地构建出来。我们将使用 <template> 标签来包裹这两种不同的视图，为下一步使用 v-if/v-else 进行动态切换打下基础。

2.2.2 视图层 (<template>) 实现

我们来分析并编写 src/views/Layout/components/LayoutNav.vue 的代码。为了在开发阶段能清晰地看到登录后的效果，我们暂时将 v-if 的条件硬编码为 true，有关于类名，我们严格遵守 BEM 规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<template>
  <nav class="app-topnav">
    <div class="container">
      <ul class="app-topnav__list">
        <template v-if="true">
          <li class="app-topnav__item"><a href="javascript:;" class="app-topnav__link"><i-ep-user
                app-topnav__icon></i-ep-user>用户</a></li>
          <li class="app-topnav__item">
            <el-popconfirm title="确认退出吗?" @confirm="handleLogout" confirm-button-text="确认" cancel-button-text="取消">
              <template #reference>
                <a href="javascript:;" class="app-topnav__link">退出登录</a>
              </template>
            </el-popconfirm>
          </li>
          <li class="app-topnav__item"><router-link to="/member/order" class="app-topnav__link">我的订单</router-link></li>
          <li class="app-topnav__item"><router-link to="/member" class="app-topnav__link">会员中心</router-link></li>
        </template>

        <template v-else>
          <li class="app-topnav__item">
            <a href="javascript:;" class="app-topnav__link">请先登录</a>
          </li>
          <li class="app-topnav__item"><a href="javascript:;" class="app-topnav__link">帮助中心</a></li>
          <li class="app-topnav__item"><a href="javascript:;" class="app-topnav__link">关于我们</a></li>
        </template>
      </ul>
    </div>
  </nav>
</template>

代码解读:

• 我们使用了 <ul> 和 <li> 构建了一个标准的导航列表。
• <el-popconfirm> 是 Element Plus 提供的气泡确认框组件，我们用它来包裹“退出登录”链接，在用户点击时提供二次确认，这是一个非常好的用户体验实践。#reference 是一个插槽，用于指定触发弹框的元素。

2.2.3 样式层 (<style>) 实现

接下来，我们为这个组件编写 SCSS 样式。这里，我们将首次使用在【模块一】中定义的全局颜色变量。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<style lang="scss" scoped>
.app-topnav {
  background: #333;

  &__list {
    display: flex;
    height: 53px;
    justify-content: flex-end;
    align-items: center;
  }

  &__item {
    // ~ 选择器：选择所有在当前元素之后的同级元素
    ~ .app-topnav__item {
      .app-topnav__link {
        border-left: 2px solid #666;
      }
    }
  }

  &__link {
    padding: 0 15px;
    color: #cdcdcd;
    line-height: 1;
    display: inline-block;

    &:hover {
      // 此处使用了我们在 var.scss 中定义的全局品牌色变量
      color: $GLColor;
    }
  }

  &__icon {
    font-size: 14px;
    margin-right: 2px;
  }
}
</style>

代码解读:

• &:hover { color: $GLColor; }: 注意，这里的 $GLColor 并非 CSS 的原生语法。它之所以能生效，是因为我们在【模块一】的 vite.config.js 中，通过 additionalData 配置，将 src/styles/var.scss 文件自动注入到了每一个 SCSS 文件中。这使得 $GLColor 成为了一个我们可以在项目中任何地方直接使用的全局变量。

2.3 Pinia 实战 - 动态化顶部通栏

现在，我们将为静态的顶部通栏注入真正的动态能力。我们将 从零开始，以前后端完整联动的专业视角，分步骤创建 可编程的模拟 API、配置开发代理、建立前端请求层、类型定义和 Pinia Store，最终实现由真实的模拟数据驱动的视图动态切换。

2.3.1 搭建专业级模拟后端

简单的 db.json 无法模拟如 POST /login 这样的非 RESTful 接口。为此，我们将 json-server 作为一个 Node.js 模块，在 Express 服务中赋予其无限的扩展能力。

1. 安装核心依赖

1

pnpm add -D json-server@0.17.4 @faker-js/faker

2. 创建模拟数据生成器 (mock/generate-data.cjs)
在项目根目录创建 mock 文件夹，并在其中新建 generate-data.cjs 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// mock/generate-data.cjs
const { faker } = require("@faker-js/faker");

// 使用 CommonJS 语法 (.cjs)，因为这是一个在 Node 环境中直接运行的脚本
module.exports = () => {
  const data = {
    // 资源必须是复数形式，如 users
    users: [],
  };

    // 2. 根据 OpenAPI 规范，创建 20 个随机模拟用户
  for (let i = 1; i <= 20; i++) {
    // 固定账号
    const account = "3381292732@qq.com";

    data.users.push({
      id: faker.string.uuid(),
      account: account,
      password: "123456",
      accessToken: faker.string.uuid(), // 修正字段名：token -> accessToken
      refreshToken: faker.string.uuid(), // 刷新令牌
      avatar: faker.image.avatar(),
      nickname: faker.person.firstName(),
      mobile: faker.phone.number({ style: "international" }),
      gender: faker.person.sex(),
      birthday: faker.date.past({ years: 30 }).toISOString().split("T")[0],
      cityCode: faker.location.zipCode(),
      provinceCode: faker.location.state({ abbreviated: true }),
      profession: faker.person.jobTitle(),
    });
  }
  return data;
};

3. 创建可编程的服务器 (mock/server.cjs)
在 mock 文件夹中，创建 server.cjs 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// mock/server.cjs
const jsonServer = require("json-server");
const generateData = require("./generate-data.cjs");

const server = jsonServer.create();
const router = jsonServer.router(generateData()); // 使用动态生成的数据
const middlewares = jsonServer.defaults();

server.use(middlewares);
server.use(jsonServer.bodyParser); // 必须启用请求体解析器，才能获取 POST 的 body

// 自定义 /login 路由，模拟登录逻辑
server.post("/login", (req, res) => {
  const { account, password } = req.body;
  const db = router.db; // 获取 lowdb 实例

  const user = db.get("users").find({ account, password }).value();

  if (user) {
    // 登录成功，返回符合项目 API 规范的成功结构
    res.status(200).json({
      code: "1", // 通常用 '1' 或 '200' 表示成功
      msg: "登录成功",
      result: user,
    });
  } else {
    // 登录失败，返回符合项目 API 规范的失败结构
    res.status(401).json({
      code: "0", // 通常用 '0' 或其他错误码表示失败
      msg: "用户名或密码错误",
      result: null
    });
  }
});

// 将所有其他请求（如 GET /users）交给 json-server 的默认路由处理
server.use(router);

const PORT = 3001;
server.listen(PORT, () => {
  console.log(`JSON Server is running on http://localhost:${PORT}`);
});

4. 更新 package.json 启动脚本

1
2
3
4
5
6

// package.json
"scripts": {
  "dev": "vite",
  "mock": "node mock/server.cjs", // 添加或更新 mock 命令
  // ...
}

5. 启动模拟服务器
打开 一个新的终端窗口，运行 pnpm run mock。我们的专业级模拟后端现在已经启动。

2.3.2 关键一步：配置 Vite 代理

现在，前端（localhost:5173）和模拟后端（localhost:3001）运行在不同的端口上，直接通信会遇到浏览器的 跨域（CORS） 限制。最佳解决方案是在开发环境中使用 Vite 内置的代理功能。

1. 配置 vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// vite.config.ts
import { defineConfig } from 'vite'
// ... 其他 import

export default defineConfig({
  // ... 其他配置
  server: {
    proxy: {
      // 关键配置：创建一个代理
      '/api': { // 匹配所有以 '/api' 开头的请求
        target: 'http://localhost:3001', // 代理的目标地址
        changeOrigin: true, // 必须开启，改变请求头的 origin
        rewrite: (path) => path.replace(/^\/api/, ''), // 重写路径，去掉 '/api' 前缀
      },
    },
  },
  // ... 其他配置
})

代码解读:

• '/api': 这是一个标识。告诉 Vite，任何看起来像 http://localhost:5173/api/xxx 的请求都需要被代理。
• target: 代理要转发到的真实后端地址。
• changeOrigin: true: 这是必选项，它会将请求头中的 Origin 字段修改为 target 的地址，以欺骗后端服务器，解决跨域问题。
• rewrite: 前端为了触发代理，请求了 /api/login，但我们的后端接口实际上是 /login。rewrite 的作用就是在转发前，把路径中的 /api 前缀去掉。

2. 更新 HTTP 请求基地址
为了让所有 API 请求都自动带上 /api 前缀，我们需要配置 axios 实例。

1
2
3
4
5
6
7
8
9
10
11

// src/utils/http.ts (假设你的 axios 实例在这里)
import axios from 'axios'

const httpInstance = axios.create({
  baseURL: '/api', // 所有请求都会自动带上 /api 前缀
  timeout: 5000
})

// ... 请求/响应拦截器

export default httpInstance

2.3.3 创建 API、类型与 Store

现在，数据链路的前端部分可以安心地基于 /api 前缀来构建了。

1. 创建类型文件 src/types/user.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// src/types/user.ts

// 定义用户信息的类型接口
export interface UserInfo {
  id: string;
  account: string;
  password?: string; // 登录后不返回密码
  accessToken: string; // 统一使用 accessToken
  refreshToken: string; // 添加刷新令牌
  avatar: string;
  nickname: string;
  mobile: string;
  gender: string;
  birthday: string;
  cityCode: string;
  provinceCode: string;
  profession: string;
}

// 定义登录表单的类型接口
export interface LoginForm {
  account: string;
  password: string;
}

2. 创建 API 文件 src/apis/user.ts

1
2
3
4
5
6
7
8
9
10
11
12
13

// src/apis/user.ts
import httpInstance from "@/utils/http";
import type { LoginForm, UserInfo } from "@/types/user";

// 登录接口
// 返回包含用户信息和双 Token 的完整数据
export const loginApi = (data: LoginForm): Promise<{ result: UserInfo }> => {
  return httpInstance({
    url: "/login",
    method: "POST",
    data,
  });
};