VRChatAvatarLearn Website

VRChatAvatarLearn 的网站前端项目，基于 Vite + 原生 JavaScript，部署目标为 Cloudflare Pages。

开发前请先阅读仓库根目录的 AGENTS.md（开发规范与约束）。

技术栈

• Vite
• npm
• Vanilla JavaScript
• Material Web (@material/web)
• Cloudflare Pages

本地开发

安装依赖：

npm clean-install

启动开发服务器：

npm run dev

生产构建：

npm run build

预览构建产物：

npm run preview

文档同步机制

构建前会执行：

node scripts/fetch-docs.mjs

该脚本会从独立 docs 仓库拉取内容，复制到 public/docs-content/，并生成索引 public/docs-content/index.json。

说明：

• public/docs-content/ 是构建产物目录，不应手动维护。
• 建议在 .gitignore 中忽略 public/docs-content/。

环境变量

项目文档拉取相关环境变量如下。

必填

• DOCS_REPO_URL
  • 文档仓库地址。
  • 推荐使用 Git 远程地址形式（带 .git），例如：
    • https://github.com/CQMHV/VRChatAvatarLearn-Docs.git

可选

• DOCS_REPO_REF

  • 要拉取的分支或 tag。
  • 默认值：main

• DOCS_REPO_SUBDIR

  • 文档目录在仓库中的相对路径。
  • 默认值：docs

本地配置环境变量（PowerShell）

在当前终端会话中设置：

$env:DOCS_REPO_URL="https://github.com/CQMHV/VRChatAvatarLearn-Docs.git"
$env:DOCS_REPO_REF="main"
$env:DOCS_REPO_SUBDIR="docs"
npm.cmd run build

说明：

• 以上设置仅对当前终端会话生效。
• 若未设置 DOCS_REPO_URL，构建会生成空文档索引。

Cloudflare Pages 配置环境变量

在 Cloudflare Pages 项目中：

1. 打开 Settings -> Environment variables
2. 添加变量：
   • DOCS_REPO_URL
   • DOCS_REPO_REF（可选）
   • DOCS_REPO_SUBDIR（可选）
3. 至少为 Production 环境配置（按需同步配置 Preview）
4. 重新触发部署

目录说明（简要）

• src/：前端应用源码
• public/：静态资源
• scripts/：构建与辅助脚本
• public/theme/：主题导出文件（禁止手动修改）

注意事项

• public/theme/ 下文件来自 Material Theme Builder，禁止手动改动。
• 文档目录与排序规则由 docs 仓库中的 Markdown 和 index.md 规则控制。
• 构建阶段的文档排序/匹配异常会在构建日志中输出 warn。