# portfolio

**Repository Path**: zyxjhpz/portfolio

## Basic Information

- **Project Name**: portfolio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔗 在线体验地址

**👉 [https://zyxjhpz.gitee.io/portfolio/](https://zyxjhpz.gitee.io/portfolio/) 👈**

> [切换查看英文原版](./README-en.md)

---

# Portfolio 个人作品集网站

基于 **Vue 3 + Vite** 构建的个人作品集（Portfolio）网站，也是一份从「原生 HTML/CSS/JS」重构为「Vue 3 组件化开发」的完整前端课程实践项目，已通过 Gitee Pages 部署上线。

---

## 目录

- [项目简介](#项目简介)
- [项目背景](#项目背景)
- [主要功能](#主要功能)
- [完整技术栈](#完整技术栈)
- [环境要求](#环境要求)
- [安装依赖](#安装依赖)
- [本地运行](#本地运行)
- [打包构建](#打包构建)
- [项目目录结构与详细解释](#项目目录结构与详细解释)
- [Gitee Pages 部署说明](#gitee-pages-部署说明)
- [常见问题 FAQ](#常见问题-faq)
- [作者信息](#作者信息)

---

## 项目简介

本项目是一个单页应用（SPA）形式的个人作品集网站，包含 **首页、作品展示、关于我** 三个页面，通过 Vue Router 实现无刷新路由跳转。网站用于展示个人基本信息、技能清单与前端作品，适合作为求职简历页、个人名片或课程结业作业提交。

- 在线访问：**[https://zyxjhpz.gitee.io/portfolio/](https://zyxjhpz.gitee.io/portfolio/)**
- 代码仓库：**[https://gitee.com/zyxjhpz/portfolio](https://gitee.com/zyxjhpz/portfolio)**
- 站点作者：张馨怡（软件工程专业，前端开发方向）
- 项目类型：前端课程综合实践作业
- 代码风格：Vue 3 组合式 API（`<script setup>`）+ 单文件组件（SFC）

## 项目背景

本项目最初使用**原生三件套（HTML + CSS + JavaScript）**完成，保存在 [day03/](./day03/index.html) 目录中；随后按照课程要求，将其重构为基于 **Vue 3 + Vite** 的组件化工程，即当前 `src/` 目录下的正式版本。

重构的核心思路与收获如下：

| 原生版本（day03） | Vue 3 重构版本（src） |
| ----------------- | --------------------- |
| 手写 `document.querySelectorAll` 遍历 DOM 渲染列表 | 使用 `v-for` 指令基于数据数组渲染 |
| 通过 `classList` 手动切换 `active` 类名实现高亮 | 使用 `ref` 响应式状态 + `:class` 动态绑定 |
| 手动绑定 `addEventListener` 事件 | 直接使用 `@click`、`@mouseenter` 等模板事件 |
| 单个 HTML 文件切换「页面」 | Vue Router 多路由页面，无刷新跳转 |
| 样式集中在一个 CSS 文件 | 组件内 `<style scoped>` 样式隔离 |

通过这次重构，实践并掌握了：组件拆分与复用（导航栏 / 页脚 / 页面视图）、响应式数据驱动视图的思想、前端路由配置，以及 Vite 工程化开发与 Gitee Pages 静态部署的完整流程。

## 主要功能

### 1. 全局布局

- **顶部导航栏（NavBar）**：吸顶（`sticky`）设计，始终悬浮在页面顶部；导航链接由配置数组经 `v-for` 渲染，当前页面对应的链接自动高亮（下划线 + 变色），点击可在三个页面间无刷新切换。
- **页脚（Footer）**：全局统一的底部信息区。
- **内容区**：`App.vue` 中通过 `<RouterView />` 承载各页面，内容最大宽度 900px 居中，保证阅读体验。

### 2. 首页（`/`，HomeView）

- 展示姓名标题与个人定位一句话介绍。
- 提供「查看作品」「了解更多」两个引导按钮，分别跳转到作品页与关于页，按钮带悬停变色过渡效果。

### 3. 作品展示页（`/works`，WorksView）

- 采用 CSS Grid（`auto-fit` + `minmax`）实现**自适应卡片网格**，卡片数量变化时列数自动调整。
- 展示 3 个前端作品：个人博客页面、待办管理小应用、企业官网静态页，每个作品包含标题与简介。
- 鼠标悬浮卡片时通过 `ref` 状态驱动「上浮 + 阴影加深」交互效果（对应原生版本的 `hover-effect` 类切换逻辑）。

### 4. 关于我页（`/about`，AboutView）

- **技能清单**：4 条技能（HTML/CSS、JavaScript、Vue 基础、UI 还原）以卡片列表呈现，点击某条技能会高亮显示并通过弹窗展示详细说明。
- **联系我**：深色区块展示邮箱（`mailto:` 一键发信）与合作意向说明。

## 完整技术栈

| 分类 | 技术 / 工具 | 版本 | 作用说明 |
| ---- | ----------- | ---- | -------- |
| 核心框架 | [Vue](https://cn.vuejs.org/) | ^3.5.40 | 渐进式 JavaScript 框架，采用组合式 API 与 `<script setup>` 语法 |
| 路由 | [Vue Router](https://router.vuejs.org/zh/) | ^4.6.4 | Vue 3 官方路由，`createWebHistory`（history 模式）实现 SPA 页面切换 |
| 构建工具 | [Vite](https://cn.vite.dev/) | ^8.1.5 | 开发服务器（秒级冷启动 + 热更新）与生产构建 |
| Vue 插件 | [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue) | ^6.0.8 | 让 Vite 编译 `.vue` 单文件组件 |
| 调试工具 | [vite-plugin-vue-devtools](https://github.com/vuejs/devtools-vite) | ^8.1.5 | 在页面内集成 Vue DevTools，便于调试组件与路由 |
| 语言基础 | HTML5 / CSS3 / JavaScript (ES6+) | - | 语义化标签、Flex 与 Grid 布局、CSS 过渡动画、ES Module |
| 部署平台 | [Gitee Pages](https://gitee.com/help/articles/4136) | - | 静态站点托管，直接在线访问构建产物 |
| 开发环境 | Node.js + npm | ^22.18.0 或 >=24.12.0 | 运行时与包管理 |

## 环境要求

开始之前，请确认本地已安装：

1. **Node.js**：版本需满足 **`^22.18.0` 或 `>=24.12.0`**（与 [package.json](./package.json) 中 `engines` 字段一致）。推荐使用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 管理多版本。
2. **npm**：随 Node.js 一同安装，使用 `node -v`、`npm -v` 检查版本。
3. **Git**：用于代码版本管理与推送到 Gitee，`git --version` 检查。
4. **编辑器（推荐）**：VS Code + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) 扩展（安装后请禁用旧的 Vetur，避免冲突）。

## 安装依赖

```bash
# 1. 从 Gitee 克隆本项目
git clone https://gitee.com/zyxjhpz/portfolio.git

# 2. 进入项目根目录
cd portfolio

# 3. 安装全部依赖（首次运行前必须执行）
npm install
```

> 提示：若安装速度慢，可切换国内镜像源：`npm config set registry https://registry.npmmirror.com`

## 本地运行

```bash
# 启动开发服务器（支持模块热替换 HMR）
npm run dev
```

启动成功后，终端会输出本地访问地址（默认 **`http://localhost:5173`**），浏览器打开即可实时预览；修改源码保存后页面会自动更新，无需手动刷新。

## 打包构建

```bash
# 1. 构建生产环境产物（自动压缩、打 hash 指纹），输出到 dist/ 目录
npm run build

# 2. 本地启动静态服务器预览构建产物（验证打包结果）
npm run preview
```

说明：

- [vite.config.js](./vite.config.js) 中已配置 **`base: './'`（相对路径）**，保证部署到 Gitee Pages 的子路径 `/portfolio/` 时，JS / CSS / 图标等资源都能正确加载，不会出现页面空白。
- `dist/` 目录即最终部署产物，为纯静态文件，已一并提交到仓库中供 Gitee Pages 使用。

## 项目目录结构与详细解释

```
portfolio/
├── .vscode/                  # VS Code 编辑器配置
│   ├── extensions.json       # 打开项目时推荐安装的扩展列表（Vue 官方扩展等）
│   └── settings.json         # 工作区设置，保证编辑器行为一致
├── public/                   # 静态资源目录：构建时原样复制到 dist/，不参与打包编译
│   └── favicon.ico           # 网站标签页图标
├── src/                      # 源代码目录（核心开发目录）
│   ├── assets/               # 全局样式资源
│   │   ├── base.css          # 基础样式：CSS Reset、变量、通用元素样式
│   │   └── main.css          # 全局主样式：页面背景、字体等整体风格
│   ├── components/           # 可复用公共组件
│   │   ├── NavBar.vue        # 顶部导航栏：sticky 吸顶 + v-for 渲染链接 + 路由高亮
│   │   └── Footer.vue        # 页脚组件：版权等底部信息
│   ├── router/               # 路由模块
│   │   └── index.js          # 定义 / 、/works、/about 三条路由并创建 router 实例
│   ├── views/                # 页面级组件（与路由一一对应的"视图"）
│   │   ├── HomeView.vue      # 首页：个人介绍 + 跳转引导按钮
│   │   ├── WorksView.vue     # 作品页：Grid 自适应卡片 + hover 上浮交互
│   │   └── AboutView.vue     # 关于页：技能清单（点击高亮）+ 联系方式
│   ├── App.vue               # 根组件：组合 NavBar + RouterView + Footer 的全局骨架
│   └── main.js               # 应用入口：引入全局样式，createApp 创建实例、注册路由并挂载 #app
├── day03/                    # 重构前的原生版本存档（HTML+CSS+JS 三件套练习）
│   ├── index.html            # 原生页面结构
│   ├── css/style.css         # 原生样式
│   └── js/script.js          # 原生交互脚本（对照学习用）
├── dist/                     # 构建产物目录（npm run build 生成，已提交到仓库供 Gitee Pages 部署）
│   ├── assets/               # 打包后的 JS / CSS（带 hash 指纹，支持长效缓存）
│   ├── favicon.ico
│   └── index.html            # 入口 HTML（自动注入打包资源引用，Gitee Pages 部署必需）
├── index.html                # Vite 的 HTML 入口模板（dev 与 build 共用）
├── jsconfig.json             # JS 项目配置：为编辑器提供 @ 路径别名智能提示等
├── package.json              # 项目清单：依赖版本、scripts 脚本、engines 版本约束
├── package-lock.json         # 依赖锁定文件：保证不同机器安装的依赖版本完全一致
├── vite.config.js            # Vite 配置：base 相对路径 + vue / devtools 插件 + @ 别名
├── README.md                 # 项目说明文档（中文，即本文件）
└── README-en.md              # 项目说明文档（英文原版，备份保留）
```

**几个关键文件补充说明：**

- [vite.config.js](./vite.config.js)：`base: './'` 使构建产物全部使用相对路径引用资源，这是 Gitee Pages 子路径部署不白屏的关键；另配置了别名 `@` → `src/`，源码中可写作 `import NavBar from '@/components/NavBar.vue'`。
- [src/router/index.js](./src/router/index.js)：使用 `createWebHistory` 创建 history 模式路由；在 Gitee Pages 上站点内跳转正常，但子路径直接刷新会 404（原因与替代方案见 FAQ）。
- [src/main.js](./src/main.js)：整个应用唯一的入口，执行顺序为「引入全局样式 → 创建应用实例 → 注册路由 → 挂载到 index.html 的 #app 节点」。
- [day03/](./day03/index.html)：刻意保留的重构前版本，可作为「原生 JS vs Vue 数据驱动」的对照学习材料，不参与构建。

## Gitee Pages 部署说明

本项目的在线版本部署在 Gitee Pages 上，访问地址：**https://zyxjhpz.gitee.io/portfolio/**

### 开启前置条件

| 序号 | 条件 | 说明 |
| ---- | ---- | ---- |
| 1 | 账号完成**实名认证** | 登录 Gitee → 头像 → 设置 → 实名认证，按提示完成个人认证，未认证无法开通 Pages |
| 2 | 仓库可见性为**公开** | 私有仓库无法使用免费版 Gitee Pages；仓库首页 → 管理 → 基本信息 → 开源（公开） |
| 3 | 仓库中存在 `dist` 目录 | 且 `dist` 内**必须包含 `index.html`**；由于 Vite 项目默认不提交构建产物，需使用 `git add dist -f` 强制提交 |
| 4 | 已将代码推送到 `main` 分支 | Gitee Pages 从仓库分支读取文件进行部署 |

### 网页操作步骤

1. 确认上述前置条件全部满足，且 `npm run build` 的产物已通过 `git add dist -f` + `git push origin main` 提交到仓库。
2. 登录 Gitee，进入仓库首页：`https://gitee.com/zyxjhpz/portfolio`。
3. 点击仓库顶部的 **「服务」** 菜单，在下拉列表中选择 **「Gitee Pages」**。
4. 在部署配置页面：
   - **部署分支**：选择 `main`；
   - **部署目录**：填写 `/dist`；
   - 勾选 **「强制 HTTPS」**；
   - 其余选项保持默认。
5. 点击 **「启动」** 按钮。
6. 等待平台审核与部署（通常几分钟），页面刷新后即可看到部署成功的在线访问地址。
7. 最终获得在线访问链接：**https://zyxjhpz.gitee.io/portfolio/**

### 更新部署流程

后续修改代码后重新上线，只需三步：

```powershell
npm run build ; git add dist -f ; git commit -m "chore: 重新构建并更新dist" ; git push origin main
```

推送完成后，回到 **服务 → Gitee Pages** 页面点击 **「更新」**，等待审核完成即生效。

## 常见问题 FAQ

**Q1：执行 `npm install` 很慢或失败？**
A：切换国内镜像源后重试：
```bash
npm config set registry https://registry.npmmirror.com
npm install
```
若仍失败，删除 `node_modules/` 与 `package-lock.json` 后重新安装。

**Q2：启动时提示 Node 版本不兼容？**
A：本项目要求 Node `^22.18.0` 或 `>=24.12.0`。用 `node -v` 检查当前版本；版本不符时建议用 nvm 安装并切换：`nvm install 22` → `nvm use 22`。

**Q3：默认端口 5173 被占用了怎么办？**
A：Vite 会自动尝试下一个可用端口；也可手动指定：
```bash
npm run dev -- --port 3000
```

**Q4：Gitee Pages 上从首页点导航跳转正常，但直接刷新 `/works`、`/about` 出现 404？**
A：因为项目使用 history 路由模式，Gitee Pages 无法配置「路径回退到 index.html」。课程作业场景下建议从首页进入后通过导航栏浏览；若需要彻底支持任意子路径刷新，可将 [src/router/index.js](./src/router/index.js) 中的 `createWebHistory` 改为 `createWebHashHistory`（hash 模式，URL 会带 `#/`），重新打包提交即可。

**Q5：部署到 Gitee Pages 后页面空白？**
A：通常是资源以绝对路径 `/assets/...` 引用导致 404。确认 [vite.config.js](./vite.config.js) 已配置 `base: './'`，重新 `npm run build` 并提交 dist 后在 Gitee Pages 点击「更新」；同时用 Ctrl+F5 强制刷新浏览器缓存。

**Q6：修改了代码但在线页面没有变化？**
A：Gitee Pages 免费版不会随推送自动更新，需要手动到 **服务 → Gitee Pages** 点击 **「更新」**，并等待审核完成；确认已推送最新的 `dist/` 且本地 `npm run preview` 预览正常。

**Q7：修改了代码但本地页面没有变化？**
A：先确认 dev 服务器仍在运行（HMR 只对运行中的服务生效）；再检查浏览器缓存（Ctrl+F5 强制刷新）；若改了 `vite.config.js`，必须重启 `npm run dev`。

**Q8：`git add dist` 提示被忽略（nothing added）？**
A：`dist` 可能被 `.gitignore` 规则忽略，使用强制添加：`git add dist -f`，然后正常 commit 即可。

**Q9：`@` 别名在编辑器里报"找不到模块"？**
A：确认 [vite.config.js](./vite.config.js) 中存在 `resolve.alias` 配置，且 [jsconfig.json](./jsconfig.json) 中的 `paths` 与之对应（本仓库均已配置，正常不会出现）。

## 作者信息

**张馨怡** — 软件工程专业 · 前端开发爱好者，专注页面交互与用户界面实现。

- Gitee 主页：[https://gitee.com/zyxjhpz](https://gitee.com/zyxjhpz)
- 项目仓库：[https://gitee.com/zyxjhpz/portfolio](https://gitee.com/zyxjhpz/portfolio)
- 在线作品集：**[https://zyxjhpz.gitee.io/portfolio/](https://zyxjhpz.gitee.io/portfolio/)**
- 联系方式：见网站「关于」页邮箱，欢迎交流前端相关项目与合作。