Files

joyzhao 4621223d26 fix(i18n): improve language path handling and prevent unnecessary redirects

- Fix edge cases in path processing for language switching
- Add checks to prevent redirects to the same page
- Update documentation to reflect current project structure

2025-06-19 10:13:49 +08:00

11 KiB

Raw Blame History

项目说明文档

本文档旨在提供对 zhaoguiyang.site 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。

1. 项目概述

zhaoguiyang.site 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目。

2. 技术栈和框架

主要框架: Astro - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
UI 框架: React - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
样式: Tailwind CSS - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 @tailwindcss/vite 集成到 Astro 项目中。
动画: Framer Motion (framer-motion) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考组件，它是一个统一处理动画逻辑的封装。
图标: Lucide React - 一个简单、美观的 SVG 图标库。
包管理器: pnpm - 一个快速、磁盘空间高效的包管理器。
TypeScript: 用于类型检查和提高代码质量。

3. 组件库和 UI

自定义组件: 项目包含多个自定义 React 组件，位于 src/components/ 目录下，用于展示不同的内容区域，例如：
- HeroSection.tsx: 个人简介区域。
- ExperienceSection.tsx: 工作经历区域。
- SkillsSection.tsx: 技能展示区域。
- ProjectsSection.tsx: 项目展示区域。
- GlassHeader.tsx: 玻璃拟态效果的导航栏。
- Footer.tsx: 页脚。
- LanguageSwitcher.tsx: 语言切换组件。
- ThemeToggle.tsx: 主题切换组件 (位于 src/components/ui/)
UI 组件 (src/components/ui/): 基于 Shadcn UI 风格，提供可复用的基础 UI 元素。
- button.tsx: 按钮组件。
- card.tsx: 卡片组件 (包含 Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter)。
- glass-card.tsx: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion。
UI 辅助库:
- class-variance-authority: 用于创建可变样式的组件。
- clsx: 用于有条件地组合类名。
- tailwind-merge: 用于合并 Tailwind CSS 类名，避免冲突。
- tw-animate-css: 用于集成 Animate.css 的 Tailwind CSS 插件。
Radix UI: @radix-ui/react-slot 被用作依赖，用于构建可访问和可组合的 UI 组件。

4. 目录结构

├── .gitignore             # Git 忽略文件配置
├── .trae/                 # Trae AI 相关配置目录
│   └── rules/
│       └── project_rules.md # 本项目说明文档
├── .vscode/               # VS Code 编辑器配置
│   ├── extensions.json
│   └── launch.json
├── LICENSE                # 项目许可证
├── README.md              # 项目自述文件
├── astro.config.mjs       # Astro 配置文件
├── components.json        # Shadcn UI 组件库的配置文件
├── package.json           # 项目依赖和脚本配置
├── pnpm-lock.yaml         # pnpm 锁文件
├── public/                # 静态资源目录 (如图片、favicon)
│   ├── favicon.svg
│   └── profile.jpg
├── src/
│   ├── components/        # React 组件目录
│   │   ├── ExperienceSection.tsx
│   │   ├── Footer.tsx
│   │   ├── GlassHeader.tsx
│   │   ├── HeroSection.tsx
│   │   ├── MotionWrapper.tsx  # Framer Motion 包装组件
│   │   ├── ProjectsSection.tsx
│   │   ├── SkillsSection.tsx
│   │   ├── TimelineItem.tsx   # 时间轴条目组件
│   │   ├── LanguageSwitcher.tsx # 语言切换组件
│   │   └── ui/                # 通用 UI 组件 (基于 Shadcn UI 风格)
│   │       ├── button.tsx       # 按钮组件
│   │       ├── card.tsx         # 卡片组件
│   │       ├── glass-card.tsx   # 玻璃拟态卡片组件
│   │       └── theme-toggle.tsx # 主题切换组件
│   ├── i18n/                # 国际化相关文件
│   │   ├── ui.ts            # 存储翻译文本
│   │   └── utils.ts         # i18n 辅助函数
│   ├── layouts/             # Astro 布局组件
│   │   └── Layout.astro       # 全局页面布局
│   ├── lib/                 # 辅助函数和数据
│   │   ├── data.ts            # 存储个人信息、经历、技能等静态数据
│   │   └── utils.ts           # 通用工具函数
│   ├── pages/               # Astro 页面组件
│   │   ├── index.astro        # 网站主页 (英文)
│   │   └── zh/                # 中文语言目录
│   │       └── index.astro    # 网站主页 (中文)
│   └── styles/              # 全局样式
│       └── global.css
└── tsconfig.json          # TypeScript 配置文件

5. 关键文件说明

astro.config.mjs: 配置 Astro 项目，包括 Vite 插件（如 Tailwind CSS）和 Astro 集成（如 React）。
package.json: 定义项目元数据、依赖项和 npm 脚本（如 dev, build, preview）。
tsconfig.json: 配置 TypeScript 编译器选项，包括路径别名（@/* 指向 ./src/*）和 JSX 设置。
src/layouts/Layout.astro: 定义网站的全局 HTML 结构、头部信息（<head>）、全局样式和客户端脚本。所有页面都将使用此布局。
src/pages/index.astro: 网站的英文版入口页面。它导入并使用 Layout.astro 作为布局，并按顺序引入各个 React 内容区域组件。通过 getLangFromUrl 从 URL 判断当前语言并传递给布局和组件。client:only="react"指令表示这些 React 组件仅在客户端渲染。
src/pages/zh/index.astro: 网站的中文版入口页面，结构与 index.astro 类似，但为中文内容服务，展示个人简介、工作经历、技能和项目。
src/lib/data.ts: 存储网站展示的静态数据，如个人信息、工作经历、技能列表和项目信息。文件中的许多键值对应于 src/i18n/ui.ts 中的翻译键，以支持多语言。这使得内容易于更新和管理，而无需直接修改组件代码。
src/i18n/ui.ts: 定义了支持的语言 (英语和简体中文) 以及所有需要翻译的文本内容的键值对。是实现网站国际化的核心文件。
src/i18n/utils.ts: 包含国际化相关的辅助函数，如 getLangFromUrl (从 URL 获取当前语言)、useTranslations (提供一个 t 函数用于在组件中获取翻译文本) 和 getLocalizedPath (生成本地化路径)。
src/components/*.tsx: 构成页面主要内容的 React 组件。它们从 src/lib/data.ts 获取数据并使用 Tailwind CSS 进行样式设置，使用 Framer Motion 实现动画效果。
public/: 存放可以直接通过 URL 访问的静态文件，如 favicon.svg 和 profile.jpg。

6. 数据流和状态管理

静态数据驱动：项目主要依赖 src/lib/data.ts 中的静态数据来渲染内容。这意味着大部分内容在构建时就已经确定，无需复杂的运行时数据获取或状态管理。
无复杂状态管理：由于项目性质（个人简历/作品集），没有引入 Redux、Zustand 或 React Context 等复杂的状态管理库。组件的状态管理主要通过 React 自身的 useState 和 useEffects Hook 在组件内部完成，或者通过 props 从父组件传递。
国际化数据流：src/i18n/ui.ts 提供翻译文本，src/i18n/utils.ts 提供辅助函数来处理语言切换和文本获取，确保多语言内容正确显示。

7. 构建和部署

构建命令：项目使用 pnpm run build 命令进行构建。此命令会触发 Astro 的构建过程，将项目编译为静态文件，输出到 dist/ 目录。
部署：由于是静态网站，构建产物可以直接部署到任何静态文件托管服务，如 Netlify, Vercel, GitHub Pages 等。

8. AI 代码重构和功能开发指南

在进行代码重构或新功能开发时，请遵循以下原则：

保持 Astro 核心优势：优先使用 Astro 的 Islands 架构，确保大部分内容以静态 HTML 形式提供，仅在必要时水合（hydrate）交互式组件。
React 组件化：对于需要交互的 UI 部分，使用 React 进行组件化开发，并确保组件是可复用和可测试的。
Tailwind CSS 优先：样式应通过 Tailwind CSS 实用程序类实现。只有在 Tailwind 无法满足需求时，才考虑使用自定义 CSS。
Framer Motion 动画：所有动画效果通过 Framer Motion 实现，保持动画逻辑的统一性。
国际化支持：所有用户可见的文本通过 src/i18n/ui.ts 进行管理，确保新功能也支持多语言。
数据驱动：新功能所需的数据集中管理，例如添加到 src/lib/data.ts 中，而不是硬编码在组件内部。
性能优化：关注 Lighthouse 等工具的性能指标，确保代码更改不会引入性能瓶颈。
可访问性：确保所有 UI 元素都符合 WCAG 标准，特别是对于交互式组件。
代码质量：遵循 TypeScript 最佳实践，编写清晰、可读、有注释的代码。
测试：对于复杂逻辑或关键组件，考虑编写单元测试或集成测试。

9. 潜在的改进和扩展方向

CMS 集成：将静态数据（如项目、博客文章）迁移到 CMS（如 Contentful, Sanity, Strapi），实现更灵活的内容管理。
博客功能：添加一个简单的博客模块，用于发布文章。
国际化完善：除了文本，考虑图片、日期格式等内容的国际化。
性能监控：集成 Web Vitals 监控，持续跟踪网站性能。
SEO 优化：进一步优化元标签、结构化数据等，提升搜索引擎排名。
无障碍优化：深入研究 ARIA 属性和键盘导航，提升无障碍体验。
动画库扩展：探索 Framer Motion 更多高级特性，或集成其他动画库以实现更丰富的视觉效果。
组件库扩展：基于 Radix UI 或其他无头 UI 库构建更多可复用的组件。
测试框架引入：引入 Vitest 或 React Testing Library 等测试框架，提高代码质量和可维护性。

11 KiB Raw Blame History Unescape Escape