贡献指南

感谢你的贡献！这个项目维护着虚拟歌姬专辑的导航信息、元数据和歌词数据库。

仓库地址：https://github.com/wuyilingwei/LRC

1️⃣ 账户注册

你需要一个 GitHub 账户来贡献。

如果还没有账户，请在这里注册：
👉 GitHub 注册

2️⃣ 为什么使用 Git (GitHub)?

Git 是一个协作工具，能让许多人在同一个项目上工作而不会互相覆盖彼此的工作。

在这个项目中，我们维护着不断增长的元数据和歌词数据库。Git 让我们能够：

追踪每一次数据变更
知道谁改了什么，以及何时改的
轻松地审查和修复错误
在出现问题时恢复之前的版本
让许多贡献者安全地并行工作

采用 Github + Cloudflare Pages 的方式，能让我们自动化构建和发布。和常规的wiki相比，这不需要专用服务器维护，没有带宽和附加费用问题，且更安全、稳定。

3️⃣ 需要学习 Git 吗？

不需要！

你不需要学习 Git 命令就能贡献。

你可以选择任何你觉得舒服的方式：

直接在 👉 GitHub 在线编辑器中编辑
(推荐第一次使用 Git 的用户)
使用 Git 软件（如 GitHub Desktop安装完成后点击网页上的 Code - Open with Github Desktop）
- 克隆到你的本地电脑
- 用任何文本编辑器编辑（如 VS Code 或记事本）

更多 Git 教程：Pro Git 中文版

4️⃣ 结构与文件

📁 项目结构

.
├── res/              # 资源文件夹，存放所有专辑歌词文件
│   ├── 专辑1/
│   │   ├── cover.*  # 专辑封面（可选，支持 jpg/png/gif/webp 等格式，请文件名全部小写）
│   │   ├── meta.toml # 专辑元数据文件
│   │   └── *.lrc    # 歌词文件
│   └── 专辑2/
├── pack/             # 自动生成的专辑打包文件夹（请勿手动修改）
│   └── *.zip        # 专辑歌词包
├── .github/
│   └── scripts/      # 自动化脚本
├── docs/             # VuePress 文档源文件
│   ├── .vuepress/    # VuePress 配置文件夹
│   ├── README.md     # 网站首页内容
│   ├── about.md      # 关于页面
│   └── contributing.md # 贡献指南
├── README.md         # 项目总览和贡献指南链接
└── package.json      # 项目配置和依赖

一般情况下，你只需要编辑 res/ 目录下的相应TOML 和 LRC 文件，这些文件包含专辑的元数据和歌词内容。其他部分会自动生成和维护。

文件格式说明

本项目使用三种主要文件格式，它们都可以用任何文本编辑器打开和编辑：

1. LRC (.lrc)

用途：存储歌词和时间戳信息
特点：每行包含时间戳和对应的歌词文本
编辑工具：记事本、VS Code、任何文本编辑器
项目中的用途：每首歌曲的歌词文件

2. TOML (.toml)

用途：配置文件格式，用于存储结构化的配置数据
特点：易读易写，支持嵌套结构、数组和值类型
编辑工具：记事本、VS Code、任何文本编辑器
项目中的用途：专辑元数据和曲目信息使用 TOML 格式存储

3. Markdown (.md)

用途：超文本标记语言，用于创建结构化的文档
特点：支持标题、列表、链接、代码块等格式
编辑工具：记事本、VS Code、任何文本编辑器
项目中的用途：文档和贡献指南本身就是 MD 格式

💡 推荐编辑工具：

简单编辑：Windows 记事本或系统自带文本编辑器
专业编辑：VS Code（免费，具有语法高亮和格式验证）

专辑元数据和歌词文件

编辑 /res 目录下的相应TOML 和 LRC 文件
这些文件包含专辑的元数据和歌词内容

📋 文件结构说明

文件类型	位置	说明
meta.toml	`/res/[专辑名]/`	专辑元数据（专辑名、艺术家、发布日期等）
.lrc	`/res/[专辑名]/[曲目名]/`	歌词文件
*cover.（可选）**	`/res/[专辑名]/`	专辑封面图片（支持 jpg/png/gif/webp 等格式，文件名请全部小写）

meta.toml 详细规范

每个专辑文件夹（res/[专辑名]/）中应包含一个 meta.toml 文件，用于存储专辑元数据信息。

TOML 格式示例

发行日期 = "2025-08-12"
出品 = ["平行四界Quadimension"]
发布 = "[Bilibili](https://www.bilibili.com/video/BV1uKtSz6EgF/)"
购买 = "[淘宝](https://item.taobao.com/item.htm?id=991410246698)"
电子 = "[Dizzylab](https://dizzylab.net/)"
歌词制作 = ["某某"]
演唱 = ["苍穹", "星尘"]
作词 = ["苍穹"]
作曲 = ["Melo"]
编曲 = ["Melo"]
调校 = []
曲绘 = []
混音 = []

meta.toml 字段说明

字段	类型	是否必需	说明
发行日期	字符串	否	支持 `YYYY` / `YYYY-MM` / `YYYY-MM-DD`，用于首页排序（缺失月/日按 1 处理）
出品	字符串数组	否	专辑出品方，可包含多个联合出品方
发布	字符串	否	发布链接，支持纯 URL 或 Markdown 字符串；若包含 Bilibili BV 号会自动渲染外链播放器
购买	字符串	否	购买链接，支持纯 URL 或 Markdown 字符串（如 `[淘宝](URL) 价格`）
电子	字符串	否	电子平台链接（如 Dizzylab），支持纯 URL 或 Markdown 字符串
歌词制作	字符串数组	否	歌词制作人员列表，可包含多个制作者
演唱	字符串数组	否	演唱者列表
作词	字符串数组	否	作词者列表
作曲	字符串数组	否	作曲者列表
编曲	字符串数组	否	编曲者列表
调校	字符串数组	否	调校者列表
曲绘	字符串数组	否	曲绘人员列表
混音	字符串数组	否	混音人员列表

meta.toml 编写注意事项

所有字段都可省略，空字段会在页面中自动忽略
Markdown 渲染：发布、购买、电子 字段若填写 Markdown 格式（如 [文字](URL)），会自动渲染为可点击链接
Bilibili 播放器：发布 字段中若出现 BV 号（如 BV1uKtSz6EgF 或包含该 BV 的视频链接），专辑页会自动插入 Bilibili 外链播放器 iframe

购买字段示例：

购买 = "[淘宝](https://item.taobao.com/item.htm?id=991410246698) ￥108"

空值表示：如需明确无信息，建议使用空字符串 "" 或空数组 []

5️⃣ 修改并提交更改

所有更改都必须通过 Pull Request (PR) 提交。

这确保变更可以被审查、追踪和安全地合并。

6️⃣ 自动审核规则

✅ 自动审核会检查什么？

当你提交 PR 时，系统会自动检查你的更改：

文件大小限制

LRC 文件：单个文件不超过 20 KB
元数据文件：单个文件不超过 5 KB
cover 图片：单个文件不超过 5 MB

内容检查

文本内容有意义：至少 80% 为可识别的字符（中文、英文、标点符号等）
格式：建议采用UTF-8编码

URL 校验

URL 白名单检查：文件中的 URL 必须来自允许列表
允许的域名包括（但不限于）：
- bilibili
- 淘宝
- dizzylab
- 以及其常见变体

❌ 审核失败怎么办？

如果自动审核失败：

系统会在 PR 下评论指出具体的问题
根据错误信息修改文件
直接 Push 修改后的代码
系统会自动重新检查
全部通过后 PR 会自动合并
或者等待维护者人工审核并合并

🔟 自动发布流程

发生了什么？

当你的 PR 被合并时：

✅ PR 通过自动审核
🔄 自动化工作流触发
📦 系统生成最新的文档
📝 生成 Markdown 文档
🚀 发布到网站
🎉 你的贡献现在对所有人可见了！

💡 贡献类型

我们欢迎以下类型的贡献：

📝 元数据补充：完整化现有专辑的信息
🎵 歌词补充：增加缺失的歌词
🐛 Bug 修复：修复元数据或歌词中的错误
📚 文档改进：改进项目文档
🔧 脚本改进：优化构建或审核脚本

🎯 最佳实践

提交 PR 前的检查清单

[ ] 文件大小符合要求（LRC ≤ 20KB, 元数据 ≤ 5KB）
[ ] 元数据格式正确（TOML 语法）
[ ] 歌词格式正确（标准 LRC 格式）
[ ] 没有包含禁止的内容
[ ] URL 来自允许列表
[ ] 提交信息清晰明了

创建 PR 时

标题清晰：说明修改的内容
- ✅ 好的例子：补充"藏雪"专辑元数据 或 修复"秘宝旅人I"歌词时间戳
- ❌ 不好的例子：修改文件 或 更新
描述详细：换行描述做了什么
- 修改的专辑/曲目
- 修改的内容（例如：添加作词者、修复歌词错误等）
- 如果提交新内容，请注明数据来源
一个 PR 专注一个任务：不要在一个 PR 中混合多个不相关的修改，例如同时修改文档和资源文件。

❓ 常见问题

Q: 我的 PR 被自动审核拒绝了怎么办？

A: 不用担心！查看错误信息，根据提示修改，然后 Push 你的修改。系统会自动重新检查。

Q: 我可以编辑其他文件吗？

A: 可以，但其他文件（脚本、配置、文档等）的修改需要维护者人工审查。建议先说明为什么需要这个修改。

Q: 如何报告 Bug？

A: 在 GitHub Issues 中提交，详细描述你遇到的问题和重现步骤。

感谢你为 V宇宙词站的贡献！ ❤️

你的每一个提交都帮助我们让更多人能够欣赏虚拟歌姬的精彩作品。

附录

开发与维护