开源项目维护：从使用者到贡献者
去年开源了一个小工具，现在有 500+ Star。分享维护经历。
开源的初衷
做了一个 CLI 工具解决自己的痛点，觉得别人可能也需要，就开源了。
开源前要问自己：
| 问题 | 说明 |
|---|---|
| 解决什么问题 | 清晰的定位 |
| 谁会用 | 目标用户 |
| 维护精力 | 能坚持多久 |
项目结构
my-cli/
├── src/
│ ├── index.ts
│ ├── commands/
│ └── utils/
├── tests/
├── docs/
│ ├── README.md
│ └── CONTRIBUTING.md
├── package.json
├── LICENSE
└── .github/
├── ISSUE_TEMPLATE/
└── workflows/必备文件
| 文件 | 用途 |
|---|---|
| README.md | 项目介绍、安装、使用 |
| LICENSE | 开源协议 |
| CONTRIBUTING.md | 贡献指南 |
| CHANGELOG.md | 变更记录 |
README 怎么写
# 项目名称
一句话描述
## 特性
- 特性 1
- 特性 2
## 安装
npm install my-cli
## 快速开始
my-cli init
## 文档
详细文档
## 贡献
欢迎贡献！
## License
MIT关键：让人一眼知道项目做什么、怎么用。
处理 Issue
Issue 模板
---
name: Bug Report
about: 报告 Bug
---
**描述问题**
清晰描述遇到的问题
**复现步骤**
1. 执行 '...'
2. 输入 '....'
3. 看到错误
**期望行为**
应该发生什么
**实际行为**
实际发生了什么
**环境**
- OS: [e.g. macOS]
- Node version: [e.g. 18]
- 项目版本: [e.g. 1.0.0]响应原则
| 原则 | 说明 |
|---|---|
| 及时响应 | 24 小时内回复 |
| 友好态度 | 感谢对方反馈 |
| 明确状态 | 标签标记状态 |
| 引导贡献 | 鼓励提 PR |
Issue 标签
| 标签 | 用途 |
|---|---|
| bug | 确认的 Bug |
| feature | 功能请求 |
| help wanted | 需要帮助 |
| good first issue | 适合新手 |
| wontfix | 不打算修复 |
处理 PR
代码审查
感谢你的贡献！
请检查以下事项：
- [ ] 代码风格符合项目规范
- [ ] 添加了测试
- [ ] 更新了文档
- [ ] 提交信息清晰
审查意见：
...自动化检查
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npm test
- run: npm run lint发布流程
版本号规范
遵循语义化版本：
| 版本类型 | 说明 |
|---|---|
| Major | 不兼容的 API 变更 |
| Minor | 向后兼容的功能新增 |
| Patch | 向后兼容的问题修复 |
发布命令
# 更新版本号
npm version patch/minor/major
# 发布
npm publish
# 打 tag
git push --tagsCHANGELOG
## [1.2.0] - 2025-08-25
### Added
- 新增 xxx 功能
### Fixed
- 修复 xxx 问题
### Changed
- 优化 xxx 性能
社区建设
文档完善
- API 文档
- 使用示例
- 常见问题
积极互动
- 感谢贡献者
- 回答问题
- 收集反馈
设定预期
在 README 里说明维护状态：
## 维护状态
我会在业余时间维护这个项目。
- Bug 修复：1-3 天内
- 功能请求：视情况而定
- PR 合并：1-7 天内踩过的坑
1. Issue 质量差
很多人只说“不工作”，没有上下文。
解决：Issue 模板 + 引导补充信息。
2. PR 不规范
格式混乱、没测试、没文档。
解决：PR 模板 + CI 检查 + Review 要求。
3. 精力不够
Issue 堆积，PR 没人审。
解决：降低预期、招募协作者。
4. 功能膨胀
什么需求都想加。
解决：明确项目边界，学会拒绝。
收获
| 收获 | 说明 |
|---|---|
| 技术成长 | 代码质量要求更高 |
| 社区反馈 | 发现了很多边界情况 |
| 人脉 | 认识了很多开发者 |
| 简历亮点 | 面试时被问到很多次 |
总结
开源是有成本的，但收获也很大。
建议：
- 从小项目开始
- 写好文档
- 设定预期
- 享受过程
不是为了 Star 数，是为了分享和成长。