贡献指南
如何提交 Issue
🎯 概述
Issue 帮助我们追踪 Bug、功能需求和改进建议。一个写得好的 Issue 能帮助维护者更快地理解和解决你的问题。
Issue 类型
| 类型 | 标签 | 使用场景 |
|---|---|---|
| 🐛 Bug 反馈 | bug | 功能不按预期工作 |
| ✨ 功能建议 | enhancement | 你有改进的想法 |
| 📝 文档问题 | documentation | 文档不清楚或缺失 |
| ❓ 问题咨询 | question | 需要帮助或澄清 |
🔍 提交前请先
- 搜索已有 Issue - 你的问题可能已经有人提过了
- 查看文档 - 答案可能就在文档里
- 尝试排障 - 查看排障指南
- 更新到最新版 - 确保使用的是最新版本
🐛 Bug 反馈
模板
反馈 Bug 时，请包含以下信息：
## Bug 描述
清晰简洁地描述这个 Bug。
## 复现步骤
1. 打开 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 看到错误
## 预期行为
你期望发生什么。
## 实际行为
实际发生了什么。
## 截图
如果适用，添加截图。
## 环境信息
- 操作系统：[例如 macOS 14.0、Windows 11、Ubuntu 22.04]
- Node.js：[例如 20.10.0]
- 包管理器：[例如 bun 1.0.0、pnpm 8.0.0]
- 浏览器：[例如 Chrome 120、Safari 17]
## 补充说明
其他相关信息。
## 错误日志在此粘贴相关的错误信息
示例：好的 Bug 反馈
## Bug 描述
登录表单显示"凭证无效"，即使邮箱和密码都是正确的。
## 复现步骤
1. 打开 `/auth/login`
2. 输入有效的邮箱：[email protected]
3. 输入有效的密码
4. 点击"登录"按钮
5. 出现错误信息
## 预期行为
成功登录后应该跳转到 `/admin` 仪表盘。
## 实际行为
显示"凭证无效"错误，但账户在数据库中确实存在。
## 环境信息
- 操作系统：macOS 14.2
- Node.js：20.10.0
- 包管理器：bun 1.0.18
- 浏览器：Chrome 120
## 错误日志[auth] Error: Invalid credentials at authenticateUser (/lib/auth/auth.js:45) at POST /api/auth/login
示例：不好的 Bug 反馈 ❌
登录不了。请修复。这样的描述无法帮助我们理解或复现问题。
✨ 功能建议
模板
## 功能描述
清晰描述你想要的功能。
## 解决的问题
这个功能解决什么问题？
## 建议的方案
你设想这个功能如何工作？
## 考虑过的替代方案
你考虑过的其他解决方案。
## 补充说明
设计稿、示例或参考资料。示例：好的功能建议
## 功能描述
为后台管理面板添加深色模式支持。
## 解决的问题
目前后台只有亮色主题，长时间使用会导致眼睛疲劳，尤其是在夜间。
## 建议的方案
1. 在头部添加主题切换按钮
2. 将偏好设置保存到 localStorage
3. 使用 CSS 变量实现主题颜色
4. 支持跟随系统偏好设置
## 考虑过的替代方案
- 浏览器扩展实现深色模式（不理想，会影响样式）
- 手动覆盖 CSS（不易维护）
## 补充说明
参考：Ant Design 有类似的实现可以作为参考。📝 文档问题
模板
## 文档位置
哪个文档页面有问题？
## 问题描述
什么地方不清楚、缺失或错误？
## 改进建议
如何改进？
## 补充说明
相关链接或示例。示例
## 文档位置
/docs/admin/guides/SMART_CRUD
## 问题描述
自定义行操作的部分没有说明如何添加确认对话框。
## 改进建议
添加一个示例展示：
```javascript
customRowActions={[
{
key: 'delete',
label: '删除',
confirm: {
title: '确定要删除吗？',
content: '此操作无法撤销。'
},
onClick: handleDelete
}
]}补充说明
我不得不翻阅源码才找到这个用法。
---
## 💡 技巧
### 应该做 ✅
- **具体明确** - 包含准确的错误信息和步骤
- **提供上下文** - 环境、版本、相关配置
- **一个 Issue 一个问题** - 不要混合多个问题
- **使用格式化** - 代码块、标题、列表
- **保持耐心** - 维护者通常是志愿者
- **及时跟进** - 及时回复问题
### 不应该做 ❌
- **重复提交** - 先搜索
- **描述模糊** - "不能用了"没有帮助
- **包含敏感信息** - 隐藏密码、API 密钥
- **要求立即修复** - 这是开源项目
- **态度恶劣** - 我们都是来帮忙的
---
## 🏷️ Issue 标签
常见标签说明：
| 标签 | 含义 |
|:---|:---|
| `bug` | 已确认的 Bug |
| `enhancement` | 功能需求 |
| `documentation` | 文档改进 |
| `good first issue` | 适合新手 |
| `help wanted` | 需要贡献者 |
| `wontfix` | 不会处理 |
| `duplicate` | 重复的问题 |
| `needs info` | 需要更多信息 |
---
## 🔄 Issue 生命周期- 已创建 → Issue 已提交
- 已分类 → 维护者审核并打标签
- 已确认 → Issue 有效且被接受
- 进行中 → 有人在处理
- 已解决 → 修复已合并或问题已回答
- 已关闭 → Issue 完成
---
## 📋 快速参考
### Bug 反馈最少需要
- [ ] 发生了什么
- [ ] 你期望什么
- [ ] 如何复现
- [ ] 错误信息（如有）
- [ ] 环境信息
### 功能建议最少需要
- [ ] 你想要什么
- [ ] 为什么想要
- [ ] 可能如何实现
---
## 📚 相关文档
<Cards className="not-prose grid gap-4 md:grid-cols-2">
<Card
title="提交 Pull Request"
description="想自己修复？这是方法"
href="/docs/contributing/PULL_REQUEST"
/>
<Card
title="排障指南"
description="先查看常见问题的解决方案"
href="/docs/troubleshooting"
/>
<Card
title="贡献指南"
description="总体贡献指南"
href="/docs/contributing"
/>
</Cards>