azek431-home

azek431-home 是 Azek431 的个人主站与内容导航项目。

这个仓库用于维护一个长期使用的个人主页，它的核心定位不是复杂后台系统，也不是单纯博客项目，而是一个以 个人主页、项目导航、内容聚合、公开入口 为中心的静态网站。

这个网站会作为 Azek431 的个人数字中枢，用来集中展示个人介绍、项目作品、学习记录、公开链接，以及后续博客、项目官网、工具站和更多公开内容入口。

项目主题

Azek431 Digital Nexus

Digital Nexus 可以理解为“数字连接中枢”。

在这个项目里，它代表 Azek431 的个人数字入口，用来连接：

• 个人介绍
• 项目作品
• GitHub 主页
• 学习记录
• 常用链接
• 未来博客
• 项目官网
• 更多公开内容入口

这个站点不是为了堆很多复杂功能，而是为了让访问者能快速了解 Azek431，并且通过一个统一入口访问相关内容。

项目用途

这个网站主要用于：

• 展示 Azek431 的个人主页
• 整理个人项目入口
• 聚合 GitHub、项目、链接等公开入口
• 承载未来博客、项目官网、学习记录等内容入口
• 作为后续个人网站体系的主导航
• 让访问者快速了解这个账号正在建设和维护的内容

简单来说，这个仓库维护的是 Azek431 的主站，也可以理解为个人内容生态的首页。

项目定位

定位	说明
个人主站	作为 Azek431 的个人首页和公开入口
内容导航	聚合博客、项目、链接、学习记录等入口
项目展示	展示当前和后续维护的项目内容
个人入口	让访问者快速了解 Azek431 的公开内容
长期维护项目	作为后续个人网站体系的基础入口

这个仓库只负责维护主站，不把所有博客文章、项目官网、工具项目都混在同一个仓库中。

后续如果创建个人博客、项目官网、工具站或文档站，建议分别使用独立仓库维护，再从这个主站统一跳转。

当前网站功能

当前主站已经具备以下功能：

功能	说明
首页展示	展示个人介绍、网站定位和主要入口
顶部导航	提供首页、关于、项目、链接和 GitHub 入口
关于页面	用于介绍个人方向、兴趣和网站内容规划
项目页面	用于展示项目入口、项目状态和项目分类
链接页面	用于整理公开链接和常用入口
自定义 404	提供更完整的网站访问体验
响应式布局	适配桌面端和移动端显示
移动端优化	针对手机端导航、标题、按钮、卡片和留白进行优化
统一布局	使用公共布局管理页面结构
组件化结构	使用 Header、Footer、NavCard、PageHero 等组件
数据集中管理	使用 src/data/site.ts 管理站点数据
全局样式系统	使用 src/styles/global.css 管理视觉风格
链接状态优化	对外链、占位链接和禁用卡片进行统一处理
基础可访问性	提供键盘聚焦样式和减少动态效果适配
代码格式化	使用 Prettier 统一代码和文档格式
静态构建	构建后输出为静态文件，适合部署到静态网站平台
搜索引擎基础配置	使用 robots.txt 提供基础抓取规则

当前页面

页面路径	页面说明
/	首页，展示个人介绍、主站定位和主要入口
/about/	关于页，介绍个人方向、兴趣和网站内容定位
/projects/	项目页，用于展示当前和后续项目入口
/links/	链接页，用于整理 GitHub、项目和公开链接
/404.html	自定义 404 页面

当前实现快照

截至当前版本，主站已经扩展为 16 个静态页面，并额外生成 RSS 与 Sitemap：

路径	说明
/	首页与主站总览
/about/	关于页与个人方向
/projects/	项目列表
/projects/[slug]/	项目详情页
/links/	公开链接集合与分类筛选
/now/	最近正在做的事
/uses/	日常装备和工具
/blog/	博客筹备入口
/colophon/	技术栈、字体、设计原则与灵感
/changelog/	版本更新日志
/stats/	项目、迭代、内容和访问统计
/search/	站内搜索
/rss.xml	RSS 订阅源
/sitemap.xml	XML 站点地图
/404.html	自定义 404

当前主要组件包括 Header、Footer、NavCard、PageHero、Breadcrumb、Roadmap、ThemeToggle 和 Toast。 数据分为 site.ts、projects.ts、changelog.ts、search.ts 四个模块，其中项目列表由项目详情数据派生，避免重复维护。 提交前建议运行 pnpm verify，它会依次检查格式、Astro 类型与生产构建。

页面路由

源文件	路由
src/pages/index.astro	/
src/pages/about.astro	/about/
src/pages/projects.astro	/projects/
src/pages/links.astro	/links/
src/pages/404.astro	/404.html

技术栈

技术	作用
Astro	构建静态内容型网站
TypeScript	管理站点数据和类型提示
CSS	实现页面布局、视觉样式和响应式适配
pnpm	管理项目依赖
Prettier	统一代码和文档格式
Git	本地版本管理
GitHub	远程代码托管和项目展示
Cloudflare Pages	静态网站部署平台

为什么使用 Astro

这个项目选择 Astro，主要是因为它适合构建个人主页、博客、文档站和导航站。

Astro 的优势包括：

• 适合内容型网站
• 静态构建性能好
• 页面加载速度快
• 项目结构清晰
• 不需要复杂后端
• 适合后续扩展页面
• 适合部署到静态网站平台
• 对个人主页和导航站非常友好

项目结构

azek431-home/
├─ public/
│  ├─ favicon.svg
│  ├─ robots.txt
│  └─ 静态资源
│
├─ src/
│  ├─ components/
│  │  ├─ Footer.astro
│  │  ├─ Header.astro
│  │  ├─ NavCard.astro
│  │  └─ PageHero.astro
│  │
│  ├─ data/
│  │  └─ site.ts
│  │
│  ├─ layouts/
│  │  └─ BaseLayout.astro
│  │
│  ├─ pages/
│  │  ├─ 404.astro
│  │  ├─ about.astro
│  │  ├─ index.astro
│  │  ├─ links.astro
│  │  └─ projects.astro
│  │
│  └─ styles/
│     └─ global.css
│
├─ .editorconfig
├─ .gitattributes
├─ .gitignore
├─ .prettierignore
├─ .prettierrc
├─ astro.config.mjs
├─ package.json
├─ pnpm-lock.yaml
├─ README.md
└─ tsconfig.json

目录说明

public/

public 目录用于存放静态资源。

适合放置：

• favicon
• Logo
• 站点图标
• Open Graph 图片
• robots.txt
• 其他不需要经过构建工具处理的静态文件

放在 public 中的文件会被原样复制到最终构建结果中。

src/components/

src/components 用于存放可复用组件。

当前组件：

组件	作用
Header.astro	顶部导航组件
Footer.astro	页脚组件
NavCard.astro	首页、项目页、链接页使用的导航卡片组件
PageHero.astro	页面顶部标题区组件

组件化可以减少重复代码，让页面结构更清晰，也方便后续维护和扩展。

src/data/

src/data 用于集中管理站点数据。

当前主要文件：

文件	作用
site.ts	管理站点配置、导航、首页卡片、项目数据和链接数据

把内容放在 site.ts 中，可以减少页面里的硬编码内容。后续新增项目、修改链接、调整导航时，只需要集中修改数据文件。

src/layouts/

src/layouts 用于存放页面布局。

当前主要布局：

文件	作用
BaseLayout.astro	统一管理 HTML 基础结构、SEO 信息、Header、Footer 和全局样式

BaseLayout.astro 是当前所有主要页面的基础布局。

它负责：

• 页面标题
• 页面描述
• SEO 基础信息
• 顶部导航
• 页脚
• 页面主体结构
• 全局样式引入

src/pages/

src/pages 是 Astro 的页面路由目录。

Astro 会根据这个目录中的文件自动生成页面路由。

当前页面：

文件	页面
index.astro	首页
about.astro	关于页
projects.astro	项目页
links.astro	链接页
404.astro	自定义 404 页面

src/styles/

src/styles 用于存放全局样式。

当前主要文件：

文件	作用
global.css	管理全局变量、基础样式、页面布局、卡片样式、响应式适配和移动端优化

核心组件说明

Header.astro

顶部导航组件。

主要负责：

• 显示站点名称
• 展示导航链接
• 标记当前页面状态
• 提供 GitHub 等外部入口
• 保持桌面端和移动端导航体验一致

Footer.astro

页脚组件。

主要负责：

• 展示基础版权信息
• 展示站点说明
• 作为页面底部统一收尾区域

NavCard.astro

导航卡片组件。

这个组件用于首页、项目页和链接页，是当前项目里比较核心的复用组件。

它支持：

• 标题
• 描述
• 链接
• 状态
• 分类
• 标签
• 外部链接判断
• 占位链接判断
• 禁用状态展示

当前优化点包括：

• 外部链接自动使用新窗口打开
• 外链自动添加 noopener noreferrer
• href 为空或 # 时识别为占位入口
• 未开放入口不会表现为普通跳转链接
• 保留统一卡片样式，保证页面视觉一致

PageHero.astro

页面顶部标题区组件。

主要负责：

• 页面标题
• 页面描述
• 页面顶部视觉层级
• 让首页、关于页、项目页、链接页保持统一风格

数据配置说明

项目内容主要集中在 src/data/site.ts 中管理。

这个文件适合维护：

• 网站名称
• 网站标题
• 网站描述
• 导航菜单
• 首页卡片
• 项目列表
• 链接列表
• GitHub 地址
• SEO 关键词

这种方式可以让页面更干净，也方便后续增加内容。

当前数据模块

数据项	说明
siteConfig	站点基础配置
navItems	顶部导航菜单
homeCards	首页卡片入口
projects	项目页展示数据
links	链接页展示数据

样式系统说明

项目样式主要集中在：

src/styles/global.css

当前样式系统主要负责：

• 全局颜色变量
• 页面背景
• 布局容器
• 顶部导航
• 首页 Hero
• 页面 Hero
• 卡片样式
• 按钮样式
• 项目页和链接页布局
• 自定义 404 页面
• 页脚
• 移动端适配
• 触摸体验优化
• 键盘聚焦样式
• 减少动态效果适配

移动端优化

项目已经针对手机端做了基础优化。

当前移动端优化包括：

• 顶部导航在小屏幕下更适合横向滑动
• 手机端标题字号和行高更合理
• 按钮在手机端更容易点击
• 卡片在手机端减少压迫感
• 小屏幕下内容间距更紧凑
• 降低手机端背景光效强度
• 改善项目页和链接页的阅读体验
• 移除移动端点击高亮带来的视觉干扰

这些优化让网站在手机浏览器中访问时更舒服，也更适合作为公开主页展示。

可访问性优化

当前项目已经加入一些基础可访问性优化：

• 导航和卡片保留语义化链接结构
• 外链使用更安全的打开方式
• 占位入口提供禁用状态
• 键盘 Tab 聚焦时有清晰描边
• 支持系统“减少动态效果”设置
• 手机端触摸操作更稳定

后续还可以继续增强：

• 更完整的 aria-label
• 更明确的当前页面状态
• 更完善的暗色对比度检查
• 更细致的键盘导航体验

本地开发

环境要求

建议使用：

• Node.js 22 或更高版本
• pnpm
• Git
• VS Code

安装依赖

pnpm install

启动开发服务器

pnpm dev

启动后通常访问：

http://localhost:4321/

构建项目

pnpm build

构建完成后，静态文件会输出到：

dist/

本地预览构建结果

pnpm preview

格式化代码和文档

pnpm format

检查格式

pnpm format:check

常用命令

命令	作用
pnpm install	安装项目依赖
pnpm dev	启动本地开发服务器
pnpm build	构建生产环境静态文件
pnpm preview	本地预览构建结果
pnpm check	Astro 类型与模板检查
pnpm verify	格式、类型和构建检查
pnpm format	格式化代码和文档
pnpm format:check	检查代码和文档格式
pnpm astro	执行 Astro CLI 命令

代码格式化

项目使用 Prettier 统一代码和文档格式。

相关文件：

文件	作用
.prettierrc	Prettier 配置文件
.prettierignore	Prettier 忽略规则

格式化范围包括：

• Astro 文件
• TypeScript 文件
• CSS 文件
• Markdown 文件
• JSON 配置文件

建议在提交前运行：

pnpm format

如果改动涉及页面结构、组件逻辑或构建配置，建议再运行：

pnpm build

编辑器配置

项目使用 .editorconfig 统一编辑器基础格式。

主要规则包括：

• 使用 UTF-8 编码
• 普通文本文件使用 LF 换行
• 文件末尾插入换行
• 去除行尾空格
• 使用 2 空格缩进
• Windows 脚本文件使用 CRLF

这样可以减少 Windows、Linux 和多设备开发时出现的无意义格式差异。

Git 管理说明

项目使用 Git 进行版本管理，并托管在 GitHub。

推荐开发流程：

修改代码
本地预览
运行格式化
必要时运行构建
提交 Git
推送到 GitHub
自动部署

建议每次提交只完成一个明确任务，例如：

• 更新 README
• 优化页面样式
• 新增页面内容
• 清理无用文件
• 修复构建问题
• 调整数据配置
• 优化移动端显示
• 优化组件交互

这样可以让提交记录更清晰，也方便后续回滚和排查问题。

分支说明

当前主要分支：

main

main 分支用于保存稳定版本，并作为线上部署的生产分支。

换行符规则

项目使用 .gitattributes 统一换行符规则，减少 Windows 和 Linux 多设备开发时出现无意义变更。

推荐策略：

文件类型	换行符策略
普通源码文件	LF
Windows 脚本文件	CRLF
图片、压缩包等资源	binary

忽略文件说明

项目使用 .gitignore 忽略不应该提交到仓库的内容。

常见忽略内容：

类型	示例
依赖目录	node_modules/
构建产物	dist/
Astro 生成文件	.astro/
缓存目录	.cache/、.vite/
环境变量	.env、.env.local
日志文件	*.log、pnpm-debug.log*
系统文件	.DS_Store、Thumbs.db、desktop.ini
编辑器目录	.idea/
Syncthing 冲突文件	*sync-conflict*

这些文件通常可以重新生成，或者只适合保存在本地，不适合提交到 Git 仓库。

多设备开发说明

这个项目可以在多设备之间维护，但推荐以 GitHub 作为代码版本中心。

推荐策略：

内容	推荐方式
源码文件	Git + GitHub
远程备份	GitHub
本地备份	手动同步或备份工具
依赖目录	每台设备单独安装
构建产物	每台设备本地生成
Git 内部数据库	不建议使用同步工具实时同步

不建议同步：

• .git/
• node_modules/
• dist/
• .astro/
• .vite/
• .cache/
• .env
• .stversions/
• *sync-conflict*

原因是这些目录或文件要么可以重新生成，要么会频繁变化。尤其是 .git/ 属于 Git 内部数据库，不适合被 Syncthing 这类文件同步工具实时同步，否则可能产生冲突文件或仓库状态异常。

更推荐的方式是：

Windows 主力开发
GitHub 作为远程代码中心
其他设备通过 git clone / git pull 获取代码
U 盘或同步工具只做源码备份，不实时同步 .git 和 node_modules

部署说明

项目适合部署为静态网站。

推荐构建配置：

配置项	值
构建命令	pnpm build
输出目录	dist
生产分支	main
项目类型	静态网站

每次推送到 main 分支后，可以触发线上构建和更新。

Cloudflare Pages

当前项目适合部署到 Cloudflare Pages。

推荐配置：

配置项	推荐值
Framework preset	Astro
Build command	pnpm build
Build output directory	dist
Root directory	/
Production branch	main

如果 Cloudflare Pages 提示项目与 Git 账号断开连接，需要重新连接 GitHub 授权，并确认仓库访问权限包含当前仓库。

当前状态

当前项目已经完成：

• 基础页面结构
• 首页
• 关于页
• 项目页
• 链接页
• 自定义 404 页面
• 顶部导航
• 页脚
• 可复用卡片组件
• 页面 Hero 组件
• 公共基础布局
• 集中数据配置
• 全局样式系统
• 响应式布局
• 移动端显示优化
• 卡片链接交互优化
• 键盘聚焦样式
• 减少动态效果适配
• 自定义 favicon
• robots.txt
• SEO 基础信息
• Prettier 格式化配置
• EditorConfig 编辑器配置
• Git 忽略规则优化
• GitHub 仓库托管
• Cloudflare Pages 部署流程

后续计划

后续可以继续优化：

方向	说明
About 页面增强	补充更完整的个人介绍、方向和网站规划
Projects 页面增强	增加真实项目、项目状态、项目链接和项目说明
Links 页面分类	按 GitHub、项目、工具、学习记录等分类展示
Blog 入口	后续创建独立博客仓库后从主站接入
sitemap.xml	提供站点地图
Open Graph 图片	优化社交平台分享预览
移动端细节	继续优化小屏幕显示体验
内容维护	持续更新项目、链接和个人介绍
组件抽象	后续根据需要继续拆分更细的展示组件
可访问性增强	继续优化键盘导航、语义结构和辅助说明

设计方向

项目视觉风格倾向于：

• 简洁
• 科技感
• 深色背景
• 清晰卡片
• 轻量动画
• 高可读性
• 响应式布局
• 长期可维护

整体目标是让网站既有个人特色，又保持清晰、稳定和易扩展。

仓库命名说明

仓库名：

azek431-home

含义：

部分	说明
azek431	个人标识
home	个人主站和导航入口

这个仓库只负责主站内容，不把所有后续项目都放在同一个仓库中。

适合放在这个仓库的内容

适合放在这个仓库中维护：

• 主站首页
• 关于页
• 项目导航页
• 链接集合页
• 站点基础配置
• 主站公共组件
• 主站样式系统
• 主站 README 和说明文档

不建议放在这个仓库中维护：

• 大型独立项目源码
• 完整博客系统
• 与主站无关的工具项目
• 大量文章内容
• 后端服务代码
• 数据库相关内容

如果后续有独立项目，建议新建独立仓库维护，再从主站项目页进行跳转。

维护建议

后续维护时建议遵循：

先本地预览
再格式化
必要时构建检查
最后提交并推送

推荐提交前至少执行：

pnpm format

如果修改了页面结构、组件逻辑、构建配置或依赖，建议再执行：

pnpm build

如果只是 README、文案或轻微 CSS 修改，可以先通过实时预览确认效果，等准备发布前再统一构建检查。

常见修改位置

如果需要新增或修改内容，可以优先查看：

需求	建议修改位置
修改网站名称和描述	src/data/site.ts
修改导航菜单	src/data/site.ts
新增首页卡片	src/data/site.ts
新增项目	src/data/site.ts
新增链接	src/data/site.ts
调整整体视觉	src/styles/global.css
调整页面结构	src/pages/
调整公共布局	src/layouts/BaseLayout.astro
调整顶部导航	src/components/Header.astro
调整卡片样式或逻辑	src/components/NavCard.astro

作者

Azek431

GitHub：

https://github.com/Azek431

License

当前项目主要用于个人网站建设和展示。

后续可以根据实际需要补充开源许可证。

当前实现补充：UI v2 与数字中枢视觉系统

当前主站已经从早期的普通个人主页，逐步升级为 Azek431 Digital Nexus 风格的个人数字中枢。

最新结构重点包括：

• 首页采用组件化结构，核心组件位于 src/components/home/
• HomeHero 负责首页首屏和主要行动入口
• HomeStatusConsole 负责首页运行状态面板
• HomeStats 负责首页概览数据
• HomeCommand 负责 Command Palette 风格搜索入口
• HomeProjects 负责项目精选展示
• HomeNavigation 负责主要入口矩阵
• HomeActivityNetwork 负责最近更新和公开入口
• HomeRoadmap 负责阶段规划展示
• VisualAura 负责全站背景氛围、液态玻璃光晕、鼠标光照和视觉空间感
• InterfaceFX 负责滚动进度、轻量 HUD、滚动入场和界面状态增强
• RuntimeCounter 负责 Footer 运行时间展示
• Toast、ThemeToggle、Breadcrumb 等组件负责交互、主题和页面辅助体验

样式方面，当前主要使用：

• src/styles/global.css：基础样式、旧结构兼容和全局规则
• src/styles/ui-system-v2.css：新 UI 系统、液态玻璃、高级首页、科技感、响应式和无障碍增强

当前视觉方向：

• 深色数字中枢
• 柔和液态玻璃
• 第一代主页氛围回调
• 高级卡片层级
• 科技感但不过度喧宾夺主
• 移动端和低动态偏好降级

日常开发检查

日常小改建议优先运行轻量检查：

• pnpm format:check
• pnpm check
• git diff --check

只有在发布版本、部署前最终确认、依赖或构建配置变化、大结构改动时，再运行完整验证：

• pnpm verify

本地临时备份目录 .tmp-ui-backup/ 只用于回滚和对比，不应该提交到 Git 仓库。