Personal Home Page Template

面向作品展示与个人内容发布的 Vue 3 站点模板。项目包含图库、文章、角色档案、友链、评论、Live2D 与背景音乐等模块，并内置直接读写仓库配置的本地可视化管理中心。

项目使用静态配置和静态资源，不依赖数据库或在线后台。开发完成后可构建为纯静态站点，部署到 GitHub Pages 或其他静态托管平台。

使用前必读

仓库中的示例头像、插画、角色设计、文字资料及其他素材仅用于演示，不随代码以 MIT License 授权。

在公开部署前，请至少完成以下替换：

内容	位置
头像与站点素材	public/assets/
个人资料	src/config/personal.json5
站点名称与版权	src/config/app.json5
SEO 与分享信息	src/config/html.json5
图库、文章与角色内容	src/config/images/、articles/、character-profiles/
评论、图标等外部服务	src/config/giscus.json5、fontawesome.json5

代码许可与素材权利的完整说明见许可证与素材版权。

主要能力

• 响应式个人主页，支持浅色与深色主题。
• 中文、英文、日文界面与内容配置。
• 支持分类、标签、搜索和多图查看的作品图库。
• 支持 Markdown、多语言正文、分类与评论的文章系统。
• 支持角色、差分、图片和信息卡片的层级式角色档案。
• 友链、Giscus 评论、背景音乐、Live2D 和站点识别规则。
• 自动生成缩略图、Feed、配置聚合文件和 ID 映射。
• 内置本地管理中心，提供结构化表单、拖拽排序、素材上传和文件管理。
• 配置校验、类型检查、代码检查与 GitHub Pages 工作流。

快速开始

环境要求

• Node.js ^20.19.0 或 >=22.12.0
• npm

安装与启动

git clone https://github.com/BAKAOLC/PersonalHomePageTemplate.git
cd PersonalHomePageTemplate
npm install
npm run admin

npm run admin 会同时启动：

• 站点预览：http://127.0.0.1:5173/
• 管理中心：http://127.0.0.1:5174/admin/

管理中心自动绑定当前仓库，直接读写原有 JSON5 配置和 public/assets 素材，不会创建数据库，也不会自动执行 Git 操作。

如果只需要开发站点前台：

npm run dev

推荐配置流程

1. 替换基础资料

进入管理中心后，优先完成以下模块：

1. “首页与个人资料”：头像、名称、简介、社交链接和背景。
2. “站点与首页”：站点标题、版权、SEO、语言和首页卡片。
3. “功能开关”：关闭暂时不需要的图库、文章、友链、评论或 Live2D。
4. “集成与识别规则”：按需配置 Giscus、FontAwesome 和外部站点规则。

配置文件也可以直接编辑。项目使用 JSON5，因此允许注释和尾随逗号。

2. 管理内容

集合内容按“一项一个源文件”组织：

内容	源目录	聚合结果
图库作品	src/config/images/	src/config/images.json5
文章	src/config/articles/	src/config/articles.json5
角色档案	src/config/character-profiles/	src/config/character-profiles.json5

聚合结果由开发服务器或构建脚本自动生成，不应手工维护。管理中心负责源文件的新建、复制、重命名、删除、校验和保存冲突检测。

图库配置保持项目原有语义：单图使用 src；多图使用 childImages，由现有配置合并逻辑处理共享信息。

3. 上传与引用素材

所有站点素材位于 public/assets/。管理中心的素材库可以在任意图片或文件字段中打开，并支持：

• 文件夹树、网格和列表视图；
• 拖放或批量上传；
• 新建文件夹、搜索、筛选和排序；
• 复制路径、复制文件、移动、重命名和删除；
• 图片、音频、视频及常见文档预览；
• 在选择素材后直接写回当前配置字段。

public/assets/thumbnails/ 是自动生成目录，不作为可编辑素材显示。

更完整的操作与安全边界说明见 docs/ADMIN.md。

4. 检查并构建

npm run ci:check
npm run build
npm run preview

生产文件输出到 dist/。

配置体系

多语言文本

内容字段支持两种写法：

// 所有语言共用
"name": "Example"

// 分语言配置
"name": {
  "zh": "示例",
  "en": "Example",
  "jp": "サンプル",
}

管理中心一次只显示当前编辑语言，保存时继续使用项目原有的多语言对象结构。界面固定文案位于 src/i18n/，可编辑内容位于 src/config/。

核心配置

文件	用途
app.json5	站点标题与版权信息
html.json5	HTML metadata、分享图、站点 URL 与主题色
personal.json5	头像、个人介绍、社交链接和背景
features.json5	页面模块、评论和查看器界面开关
languages.json5	可用内容语言及回退策略
characters.json5	图库引用的角色索引
tags.json5	图库标签
articles-categories.json5	文章分类
links.json5	友链标签、分类和条目
giscus.json5	Giscus 评论配置
bgm.json5	背景音乐与播放器配置
live2d.json5 / live2d-engine.json5	Live2D 展示与运行时配置
fontawesome.json5	FontAwesome Kit 与图标设置
sites.json5	外部站点识别规则

配置结构的权威来源是 src/admin/schema.ts、src/admin/fields.ts 和 src/config/validation.ts。新增字段时应同步更新运行时类型、管理表单和校验规则。

常用命令

命令	作用
npm run admin	同时启动站点与管理中心，并打开管理页面
npm run admin:ui:no-open	只启动管理中心，不自动打开浏览器
npm run dev	启动站点开发服务器
npm run build	生成聚合配置、缩略图和 Feed 后构建站点
npm run preview	本地预览 dist/
npm run typecheck	检查站点 TypeScript 类型
npm run lint	运行 ESLint
npm run admin:check	检查管理端类型、配置往返兼容和生产构建
npm run ci:check	执行项目完整质量检查与 CI 构建
npm run generate-thumbnails	重新扫描并生成图片缩略图
npm run generate-feeds	生成 RSS、Atom 和 JSON Feed

内容聚合脚本还提供 build、split、merge 和 cleanup 操作。例如：

npm run images-config:build
npm run articles-config:build
npm run character-profiles-config:build

日常开发通常不需要手动运行这些命令，Vite 插件会监听源配置并自动更新聚合结果。

项目结构

.
├─ admin/                         # 本地管理端入口与开发 API
├─ docs/ADMIN.md                  # 管理中心详细说明
├─ public/
│  ├─ assets/                     # 原始站点素材
│  └─ feeds/                      # 自动生成的 Feed
├─ scripts/                       # 配置、缩略图、Feed 与 CI 工具
├─ src/
│  ├─ admin/                      # 管理界面、字段体系与配置编解码
│  ├─ components/                 # 站点通用组件
│  ├─ config/                     # 站点配置与集合源文件
│  ├─ i18n/                       # 站点界面翻译
│  ├─ stores/                     # Pinia 状态
│  ├─ utils/                      # 配置与内容工具
│  └─ views/                      # 页面视图
├─ vite-plugins/                  # 开发期与构建期自动化插件
├─ vite.config.ts                 # 站点构建配置
└─ vite.admin.config.ts           # 本地管理中心配置

构建与部署

GitHub Pages

仓库已包含 .github/workflows/deploy.yml。推送到 main 或 master 后，工作流会执行质量检查、构建并发布 dist/。

使用前请在仓库设置中确认 Pages 的来源为 GitHub Actions，并更新：

• src/config/html.json5 中的正式站点 URL、SEO 和分享信息；
• GitHub Pages、自定义域名或反向代理所需的路径设置；
• 如果部署在域名子路径下，vite.config.ts 中的 base 以及配置内以 / 开头的资源路径。

其他静态平台

执行 npm run build 后，将 dist/ 作为静态目录发布即可。管理中心包含本地文件写入 API，只用于开发，不应作为生产后台部署。

扩展与维护

• 新增普通配置模块：在 src/admin/schema.ts 注册资源，并在字段定义中描述表单。
• 新增复杂字段：优先复用 SchemaField.vue、MediaField.vue 和现有列表/对象字段。
• 新增配置格式转换：在 src/admin/formats.ts 中保持读取与写入对称。
• 新增约束：在 src/config/validation.ts 中补充共享 Zod 校验。
• 修改自动生成逻辑：同步检查对应的 vite-plugins/ 和 scripts/ 实现。

提交修改前建议运行：

npm run lint
npm run typecheck
npm run admin:check
npm run build

常见问题

图片没有显示

确认路径以站点公开路径书写，例如 /assets/avatar.png，并确认文件确实位于 public/assets/。缩略图异常时运行 npm run generate-thumbnails。

配置修改后没有生效

确认编辑的是集合源文件而非自动生成的聚合文件。重新启动开发服务器，或运行对应的 *-config:build 命令检查格式错误。

管理中心无法启动

管理端固定监听 127.0.0.1:5174。确认端口未被占用，并检查 Node.js 版本是否满足要求。无需选择项目目录，应从当前仓库根目录运行命令。

Giscus 评论没有加载

确认仓库已启用 Discussions、Giscus App 已获得仓库访问权限，并核对 giscus.json5 中的仓库 ID、分类 ID 和映射配置。

技术栈

• Vue 3、TypeScript、Vite
• Vue Router、Pinia、Vue I18n、VueUse
• Tailwind CSS、Naive UI、Reka UI
• Marked、Highlight.js、DOMPurify
• Sharp、Zod、SortableJS
• Giscus、PixiJS、pixi-live2d-display

许可证与素材版权

代码部分采用 MIT License。

示例素材包括但不限于 public/assets/ 中的头像与插画、角色设计和相关文字资料，其版权仍归各自作者所有，不属于 MIT 授权范围：

• 角色设计：律影映幻（Ritsukage Utsumabo）© OLC / BAKAOLC
• 艺术作品：月兔弥生（Yuetuo Yayoi）及其他原作者

你可以使用、修改和分发代码，但在自己的站点中必须移除或替换这些示例素材。使用者应自行确认所使用内容、字体、图标和外部服务符合各自许可条款。

贡献

欢迎通过 Issue 报告问题或提交 Pull Request。涉及配置格式时，请说明兼容性影响，并确保现有配置仍可读取和往返保存。