在这里插入图片描述

📖 引言

写完了 99 篇，做完了「民族图鉴」这个项目，最后一篇我们聊点不一样的——聊聊开源。

很多开发者做完一个项目，代码往仓库一扔，就完事了。但其实，把项目开源出去，可能会带来意想不到的收获：

1.1 开源的价值

价值维度 具体说明
个人成长 开源倒逼你写出更高质量的代码——因为别人会看
社区反馈 来自全球的开发者帮你找 bug、提建议、贡献代码
影响力 好的开源项目能帮你建立个人品牌，获得行业认可
学习机会 你可以从别人的 PR 中学到新的思路和写法
招聘加分 优秀的 GitHub 主页，比简历上的文字更有说服力
回馈社区 你从开源社区学到了很多，是时候回馈了

💡 开源不是目的，是手段。

不是为了开源而开源，而是通过开源的方式，让项目变得更好，也让自己变得更好。

1.2 什么项目适合开源

不是所有项目都适合开源。一个好的开源项目，通常具备以下特点：

  1. 有明确的价值：解决了某个真实存在的问题
  2. 有一定的完成度：不是半成品，至少核心功能可用
  3. 代码质量尚可：别人能看懂、能跑起来、能改得动
  4. 文档基本齐全：有 README、有使用说明、有示例
  5. 你愿意投入时间：维护开源项目是长期的事

「民族图鉴」这个项目，就很适合开源：

  • ✅ 它是一个完整的、可运行的鸿蒙应用
  • ✅ 它覆盖了鸿蒙开发的方方面面，有学习价值
  • ✅ 它有 100 篇技术文章配套，文档齐全
  • ✅ 它可以作为鸿蒙开发的学习样板

1.3 开源的心理建设

在正式开源之前，先做几个心理建设：

1. 不要怕代码写得不好

很多人不敢开源，是觉得"我的代码太烂了，不好意思给别人看"。

其实没关系——

  • 没有人一开始就能写出完美的代码
  • 开源的过程，就是代码不断变好的过程
  • 比起"完美的代码"，社区更看重"真实的项目"和"持续的改进"

2. 不要期望太高

不要以为一开源就会有很多 Star、很多 Contributor。

大部分开源项目，都是从 0 开始的——

  • 第一个 Star 可能是你自己点的
  • 第一个 PR 可能是修了个错别字
  • 半年没人问津，是常态

但这没关系。开源不是短跑，是马拉松。

3. 要有边界感

开源不意味着"你要为所有人免费打工"。

  • 你可以决定接受什么 PR，不接受什么 PR
  • 你可以决定项目的方向和节奏
  • 你可以说"这个功能我不打算做"
  • 你可以休息，可以断更，可以归档

🎯 开源的第一原则：让自己开心。

如果开源变成了负担，那就失去了它本来的意义。

💡 需求分析

磨刀不误砍柴工。在把代码扔到 GitHub 之前，先做好这些准备工作。

2.1 代码检查与清理

2.1.1 敏感信息检查

这是最重要的一步——绝对不能把敏感信息提交到开源仓库。

需要检查的内容：

类型 示例 处理方式
密钥/Token API Key、Access Key、签名密钥 移到环境变量，用 .env.example 做模板
账号密码 数据库账号、后台管理员密码 全部移除，用占位符替代
个人信息 手机号、邮箱、身份证号 脱敏处理或移除
内部地址 内网 IP、内部服务器地址 改成示例地址
业务配置 内部业务开关、灰度配置 重置为默认值

「民族图鉴」项目中的敏感信息检查清单：

# 1. 检查硬编码的密钥
grep -r "apiKey\|API_KEY\|secret\|SECRET" --include="*.ts" --include="*.ets" .

# 2. 检查手机号、邮箱等个人信息
grep -r "1[3-9]\d{9}\|@.*\.com" --include="*.ts" --include="*.ets" .

# 3. 检查内部地址
grep -r "192\.168\.\|10\.\|localhost:8080" --include="*.ts" .
2.1.2 代码质量检查

开源的代码，至少要过自己这一关：

  1. 代码能跑通：至少在你的机器上是能正常运行的
  2. 没有编译错误：Lint 检查通过，没有红色报错
  3. 命名基本规范：变量名、函数名能见名知意
  4. 关键逻辑有注释：复杂的地方有说明，别人能看懂
  5. 没有明显的 bug：核心功能是正常工作的
2.1.3 移除冗余代码

把那些"写了但没用"的代码清理掉：

  • 注释掉的大段代码（如果需要，用 Git 历史回溯）
  • 没被调用的函数、没被使用的变量
  • 废弃的组件、废弃的页面
  • 临时文件、调试文件、测试文件

💡 清理的度：

不要追求"一次性清理干净"——那是不可能的。

先把最明显的冗余去掉，剩下的可以在后续迭代中慢慢优化。

2.2 仓库结构整理

一个结构清晰的仓库，能让来访者快速找到想要的东西。

「民族图鉴」的推荐目录结构：

ethnic-album/
├── entry/                    # 主应用模块
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── models/       # 数据模型
│   │   │   ├── services/     # 服务层
│   │   │   ├── pages/        # 页面
│   │   │   ├── components/   # 组件
│   │   │   └── utils/        # 工具函数
│   │   ├── resources/        # 资源文件
│   │   └── module.json5
│   └── build-profile.json5
├── articles/                 # 100篇技术文章
│   ├── article_01_intro.md
│   ├── article_02_env_setup.md
│   └── ...
├── docs/                     # 项目文档
│   ├── README.md             # 项目说明
│   ├── CONTRIBUTING.md       # 贡献指南
│   ├── CHANGELOG.md          # 变更日志
│   ├── FAQ.md                # 常见问题
│   └── article-plan-100.md   # 文章计划表
├── screenshots/              # 应用截图
│   ├── home.png
│   ├── detail.png
│   └── ...
├── .gitignore
├── LICENSE                   # 开源协议
└── README.md                 # 项目首页

整理原则：

  • 源代码放 entry/ 或 src/，不要堆在根目录
  • 文档放 docs/，和代码分开
  • 图片等静态资源放 screenshots/ 或 assets/
  • 配置文件（.gitignore、LICENSE 等）放根目录

2.3 开源协议选择

开源协议是开源项目的"法律基础"——它告诉别人"你可以用我的代码做什么，不可以做什么"。

常见的开源协议对比：

协议 要求 允许商业使用 允许修改 允许闭源 流行度
MIT 保留版权声明 ✅ ✅ ✅ ⭐⭐⭐⭐⭐
Apache 2.0 保留版权、说明修改 ✅ ✅ ✅ ⭐⭐⭐⭐
GPL v3 衍生作品也必须GPL开源 ✅ ✅ ❌ ⭐⭐⭐
BSD 3-Clause 保留版权、不使用作者名义推广 ✅ ✅ ✅ ⭐⭐⭐
MPL 2.0 修改的文件要开源，新增文件可以闭源 ✅ ✅ ⚠️ ⭐⭐

对于「民族图鉴」这类学习型项目，推荐使用 MIT 协议：

  • 最宽松，限制最少
  • 别人可以随意使用、修改、分发
  • 只需要保留版权声明就行
  • 最有利于项目的传播和推广

MIT 协议模板：

MIT License

Copyright (c) 2026 民族图鉴项目组

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

⚠️ 注意：

我不是律师，以上只是常识性介绍。

如果你的项目涉及商业合作、专利等复杂情况，建议咨询专业人士。

🛠️ 核心实现

README 是项目的"门面"——别人点进你的仓库，第一眼看到的就是它。

一个好的 README，能让访客在 30 秒内搞清楚：

  • 这是什么项目？
  • 它能做什么？
  • 我怎么跑起来？
  • 我怎么参与？

3.1 README 的标准结构

一个完整的 README，通常包含这些部分：

# 项目名称

一句话描述这个项目是干什么的。

## 功能特性

- 特性一：一句话说明
- 特性二：一句话说明
- 特性三：一句话说明

## 快速开始

### 环境要求

- HarmonyOS NEXT (API 26+)
- DevEco Studio 5.0+
- Node.js 18+

### 安装与运行

1. 克隆仓库
2. 用 DevEco Studio 打开
3. 连接设备或启动模拟器
4. 点击运行

## 项目结构

简单介绍项目的目录结构。

## 技术栈

- ArkTS / TypeScript
- ArkUI 声明式开发
- ...

## 贡献指南

欢迎贡献代码！请查看 CONTRIBUTING.md 了解如何参与。

## 许可证

MIT License

3.2 「民族图鉴」README 实战

让我们为「民族图鉴」写一个高质量的 README：

# 民族图鉴 - Ethnic Album

一款展示中国56个民族文化的鸿蒙原生应用，配套100篇技术文章，从零到一完整呈现 HarmonyOS 应用开发全流程。

<p align="center">
  <img src="./screenshots/home.png" width="200" alt="首页" />
  <img src="./screenshots/detail.png" width="200" alt="详情页" />
  <img src="./screenshots/list.png" width="200" alt="列表页" />
</p>

## ✨ 功能特性

- 🏛️ **56个民族百科**：人口、分布、语言、节日、服饰、美食等全方位介绍
- 🗺️ **民族分布地图**：地图可视化展示各民族主要分布地区
- 🎵 **民族音乐欣赏**：精选各民族经典音乐，支持后台播放
- 🎙️ **语音朗读**：TTS语音播报民族介绍，解放双眼
- 🤖 **AI问答助手**：基于大模型的民族知识智能问答
- 📝 **知识测验**：答题闯关，检验你的民族知识储备
- 🌙 **深色模式**：支持浅色/深色/跟随系统三种主题
- 🌍 **多语言**：支持中文/英文/藏语/维语等多语言
- ⭐ **收藏功能**：收藏你喜欢的民族，随时回看
- 📱 **多端适配**：手机、平板、折叠屏、车机全适配

## 📚 配套文章

本项目配套 **100篇鸿蒙开发技术文章**，从入门到进阶，覆盖：

| 篇章 | 篇数 | 核心内容 |
|------|------|---------|
| 入门基础篇 | 10篇 | 环境搭建、ArkTS基础、声明式UI |
| 页面开发篇 | 20篇 | 20+核心页面的设计与实现 |
| 数据与服务篇 | 10篇 | 数据模型、7大核心服务 |
| 架构与工程篇 | 6篇 | 分层架构、组件化、性能优化、工程化 |
| 功能进阶篇 | 14篇 | 动画、手势、弹窗、列表、表单... |
| 性能优化篇 | 10篇 | 启动、渲染、内存、包体积、功耗 |
| 鸿蒙7新特性篇 | 20篇 | AI、3D、空间音频、分布式、端云一体 |
| 实战项目篇 | 10篇 | 重构、模块化、CI/CD、上架、运营 |

全部文章请查看 [articles](./articles) 目录。

## 🚀 快速开始

### 环境要求

| 工具 | 版本要求 |
|------|---------|
| DevEco Studio | 5.0+ |
| HarmonyOS SDK | API 26 (NEXT) |
| Node.js | 18+ |

### 运行步骤

1. **克隆仓库**
   ```bash
   git clone https://github.com/yourname/ethnic-album.git
   cd ethnic-album

  1. 打开项目

    • 启动 DevEco Studio
    • 选择 “Open”，打开项目根目录
    • 等待依赖同步完成

  2. 运行应用

    • 连接鸿蒙设备（开发者模式 + USB调试）
    • 或启动远程模拟器
    • 点击顶部运行按钮 ▶️

🏗️ 项目架构

entry/src/main/ets/
├── models/          # 数据模型层
│   ├── EthnicModels.ets      # 民族核心模型
│   └── ApiTypes.ets          # API相关类型
├── services/        # 服务层（单例）
│   ├── StorageService.ets    # 本地存储服务
│   ├── ThemeService.ets      # 主题切换服务
│   ├── I18nService.ets       # 国际化服务
│   ├── MusicService.ets      # 音乐播放服务
│   ├── TTSEngineService.ets  # TTS语音服务
│   ├── AIService.ets         # AI对话服务
│   └── ApiService.ets        # API数据服务
├── pages/           # 页面层
│   ├── SplashPage.ets        # 启动页
│   ├── HomePage.ets          # 首页
│   ├── EthnicListPage.ets    # 民族列表页
│   ├── EthnicDetailPage.ets  # 民族详情页
│   └── ...
├── components/      # 组件层
│   ├── EthnicCard.ets        # 民族卡片
│   ├── SearchBar.ets         # 搜索框
│   └── ...
└── utils/           # 工具层
    ├── format.ts            # 格式化工具
    └── logger.ts            # 日志工具

架构特点：

  • 四层分层架构：表现层 → 服务层 → 数据层 → 基础设施层
  • 单一职责：每个模块只做一件事
  • 单向依赖：上层依赖下层，下层不依赖上层
  • 服务单例：全局状态统一管理

🛠️ 技术栈

类别 技术
开发语言 ArkTS / TypeScript
UI框架 ArkUI 声明式开发
状态管理 @State / @Provide / Service单例
本地存储 Preferences
网络请求 @ohos.net.http
语音合成 Core Speech Kit
AI能力 大模型API
构建工具 Hvigor
版本管理 Git

📖 学习路径

如果你是鸿蒙开发新手，建议按这个顺序学习：

  1. 入门基础篇（第1-10篇）：环境搭建 → 基础语法 → 核心概念
  2. 页面开发篇（第11-30篇）：跟着做页面，边做边学
  3. 数据与服务篇（第31-40篇）：理解服务层和状态管理
  4. 架构与工程篇（第41-46篇）：提升代码质量和工程能力
  5. 功能进阶篇（第47-60篇）：掌握更多高级功能
  6. 性能优化篇（第61-70篇）：让你的应用又快又稳
  7. 鸿蒙7新特性篇（第71-90篇）：跟上最新技术
  8. 实战项目篇（第91-100篇）：从项目到产品的完整闭环

🤝 参与贡献

我们欢迎任何形式的贡献！

  • 🐛 提交 Issue：发现 bug 或有好的建议
  • 💡 提交 PR：修复 bug、增加功能、改进文档
  • 🌍 翻译贡献：帮助翻译更多语言版本
  • 📝 内容贡献：补充民族文化资料

请查看 CONTRIBUTING.md 了解详细的贡献指南。

📄 许可证

MIT License

如果这个项目对你有帮助，点个 ⭐ Star 支持一下吧！


### 3.3 README 写作技巧

**1. 开头要有图**

人是视觉动物。一张好看的截图，比十行文字更有说服力。

建议放：
- 应用的首页截图
- 核心功能页截图
- 最好做成 GIF 动图，展示交互效果

**2. 用好 Emoji**

适当用一些 Emoji，可以让 README 更生动：
- ✨ 功能特性
- 🚀 快速开始
- 📚 文档
- 🤝 贡献指南
- 📄 许可证

但不要滥用——每个大标题前加一个就够了。

**3. 保持更新**

README 不是写完就不管了。每次发版本、每次加功能，都要记得更新 README。

一个过时的 README，比没有还糟糕——别人照着做，结果跑不起来，会觉得这个项目不靠谱。

> 🎯 **README 的黄金标准：**
>
> 一个完全不了解你项目的人，照着 README 走一遍，就能把项目跑起来。
>
> 如果他跑不起来，那就是 README 的问题，不是他的问题。

---

### 🛠️ 核心实现

有了 README，别人知道了"这是什么"、"怎么用"。

但如果有人想为项目贡献代码，他还需要知道"怎么参与"。

这时候，就需要一份 **CONTRIBUTING.md（贡献指南）**。

### 4.1 贡献指南应该包含什么

一份好的贡献指南，应该回答这些问题：

| 问题 | 说明 |
|------|------|
| **可以贡献什么？** | 哪些类型的贡献是欢迎的 |
| **怎么提交 Issue？** | Bug 报告、功能建议的模板 |
| **怎么提交 PR？** | 分支规范、提交规范、代码规范 |
| **开发环境怎么搭？** | 本地开发、测试、构建的步骤 |
| **代码规范是什么？** | 命名、格式、注释的要求 |
| **PR 多久会被 review？** | 预期的响应时间 |

### 4.2 「民族图鉴」贡献指南实战

```markdown
# 贡献指南

首先，感谢你愿意为「民族图鉴」贡献力量！🎉

无论是报告 Bug、提出建议，还是直接贡献代码，我们都非常欢迎。

## 目录

- [可以贡献什么](#可以贡献什么)
- [提交 Issue](#提交-issue)
- [提交 PR](#提交-pr)
- [开发指南](#开发指南)
- [代码规范](#代码规范)
- [常见问题](#常见问题)

## 可以贡献什么

### 🐛 Bug 报告

如果你发现了任何 bug，请提交 Issue 告诉我们。

好的 Bug 报告应该包含：
- 设备型号和系统版本
- 应用版本
- 详细的复现步骤
- 预期行为和实际行为
- 截图或录屏（如果有的话）

### 💡 功能建议

有好的想法？欢迎提出来讨论！

功能建议请说明：
- 你想要什么功能？
- 为什么需要这个功能？
- 你觉得大概应该怎么实现？（可选）

### 📝 文档贡献

文档也是项目的重要组成部分。如果你发现：
- 文档有错误
- 文档不够清晰
- 缺少示例
- 有翻译错误

欢迎提交 PR 改进文档。

### 💻 代码贡献

我们欢迎各种形式的代码贡献：
- 修复 bug
- 新增功能
- 性能优化
- 代码重构
- 单元测试

**新手友好的任务：**
我们会把一些适合新手的任务标记为 `good first issue`，欢迎认领！

## 提交 Issue

### Bug 报告模板

描述

（简要描述这个 bug）

复现步骤

  1. 打开应用
  2. 点击…
  3. 然后…

预期行为

（你觉得应该是什么样的）

实际行为

（实际发生了什么）

环境信息

  • 设备：（如 Mate 60 Pro）
  • 系统版本：（如 HarmonyOS NEXT 5.0.0）
  • 应用版本：（如 v1.0.0）

截图/录屏

（如果有的话，贴在这里）


### 功能建议模板

功能描述

（你想要什么功能）

为什么需要

（这个功能解决了什么问题）

建议方案

（你觉得大概应该怎么实现，可选）

参考

（有没有类似的实现可以参考，可选）


## 提交 PR

### PR 流程

1. **Fork 仓库**到你的 GitHub 账号
2. **创建分支**：从 `main` 分支拉一个新分支
3. **编写代码**：在你的分支上实现功能
4. **提交代码**：遵循提交规范
5. **发起 PR**：描述清楚你做了什么
6. **代码审查**：等待维护者 review
7. **合并**：review 通过后合并到 main 分支

### 分支命名规范

feature/xxx # 新功能，如 feature/dark-mode
bugfix/xxx # 修复 bug，如 bugfix/list-crash
docs/xxx # 文档更新，如 docs/readme-update
refactor/xxx # 代码重构，如 refactor/theme-service


### 提交信息规范

我们采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

():

类型：

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • style: 格式调整（不影响代码运行）
  • refactor: 代码重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建/工具/依赖等杂项

示例：
feat(theme): 新增深色模式支持
fix(list): 修复列表快速滚动时的卡顿问题
docs(readme): 更新快速开始部分的说明


### PR 描述模板

描述

（简要描述这个 PR 做了什么）

关联 Issue

（如果关联了某个 Issue，写在这里，如 Fixes #123）

改动点

  • 改动一：说明
  • 改动二：说明

测试

  • 我已经在真机上测试过了
  • 我已经添加了单元测试
  • 我已经检查过没有引入新的 lint 错误

截图/录屏

（如果是 UI 相关的改动，请放截图）


## 开发指南

### 环境搭建

1. 安装 DevEco Studio 5.0+
2. 安装 HarmonyOS NEXT SDK (API 26)
3. Fork 并克隆仓库
4. 用 DevEco Studio 打开项目

### 运行项目

1. 连接鸿蒙设备（开发者模式 + USB调试）
2. 或启动远程模拟器
3. 点击运行按钮 ▶️

### 运行测试

```bash
# 单元测试
npm run test

# Lint 检查
npm run lint

代码规范

命名规范

类型 规范 示例
变量/函数 小驼峰 camelCase userName, getUserInfo()
常量 全大写下划线 MAX_PAGE_SIZE
类/组件 大驼峰 PascalCase EthnicCard, UserService
文件名（组件） 大驼峰 EthnicCard.ets
文件名（工具） 小驼峰 formatDate.ts
文件夹 全小写短横线 ethnic-list

注释规范

  • 复杂逻辑必须有注释
  • 函数要有 JSDoc 注释（参数、返回值、说明）
  • 注释使用中文
  • 不要写"i++ // i 加一"这种废话注释

格式规范

  • 缩进：4 个空格
  • 单行不超过 120 字符
  • 运算符两侧加空格
  • 大括号同一行

其他

  • 禁止使用 any 类型，实在不确定用 unknown
  • 异步操作必须用 try-catch 捕获异常
  • 组件样式必须加 scoped
  • v-for 必须加 key，且不要用 index

常见问题

Q: PR 提交后多久会被 review？

A: 我们会尽量在 3 个工作日内 review。如果比较紧急，可以在评论里 @ 维护者。

Q: 我的 PR 被要求修改，怎么办？

A: 直接在你的分支上继续提交，PR 会自动更新。如果有不同意见，可以在评论里讨论。

Q: 可以加我觉得很酷的功能吗？

A: 建议先提 Issue 讨论一下，避免做了之后不被接受。

Q: 第一次贡献，不知道做什么？

A: 找标记为 good first issue 的任务，通常比较简单，适合上手。

再次感谢你的贡献！❤️


> 💡 **贡献指南的本质：降低参与门槛。**
>
> 你写得越详细、越清楚，别人参与的成本就越低，就越有可能贡献代码。
>
> 不要假设"别人应该知道"——把每一个贡献者都当成第一次来的新手。

---

### 🛠️ 核心实现

有人提交 Issue、有人提交 PR 了，怎么管理？

### 5.1 Issue 管理

#### 5.1.1 Issue 分类

用 Label 给 Issue 分类，方便筛选和管理：

| Label | 颜色 | 用途 |
|-------|------|------|
| `bug` | 红色 | Bug 报告 |
| `feature` | 绿色 | 功能建议 |
| `enhancement` | 蓝色 | 功能增强/优化 |
| `documentation` | 黄色 | 文档相关 |
| `good first issue` | 紫色 | 适合新手的任务 |
| `help wanted` | 橙色 | 需要帮助 / 寻求贡献者 |
| `question` | 灰色 | 问题咨询 |
| `duplicate` | 深色 | 重复的 Issue |
| `wontfix` | 灰色 | 不打算修复 / 不做 |

#### 5.1.2 Issue 处理流程

新 Issue 提交
↓
维护者 triage（分类、打标签、分配）
↓
┌─────────┬─────────┬─────────┐
│ │ │ │
Bug 功能建议 问题咨询
│ │ │
↓ ↓ ↓
确认bug 讨论可行性 回答问题
│ │ │
↓ ↓ ↓
修复 / 排期 / 关闭
标记为 接受 /
help 拒绝
wanted
│
↓
PR 修复
↓
验证通过 → 关闭


#### 5.1.3 处理 Issue 的原则

1. **及时响应**：哪怕只是说"收到了，我们看一下"，也比石沉大海好
2. **友好耐心**：对新手多一些耐心，谁都是从新手过来的
3. **说清楚原因**：拒绝一个功能建议，要说明为什么不做
4. **善用搜索**：重复的 Issue，直接指到原 Issue，然后关闭
5. **保持记录**：讨论的结论、决策的原因，都要记录下来

### 5.2 PR 管理

#### 5.2.1 PR Review 检查清单

Review PR 的时候，可以对照这个清单：

- [ ] **功能对不对**：是不是实现了它声称的功能？
- [ ] **有没有 bug**：逻辑有没有问题？边界情况考虑了吗？
- [ ] **代码质量**：命名规范吗？注释清楚吗？有没有冗余代码？
- [ ] **性能影响**：会不会引入性能问题？
- [ ] **安全风险**：有没有注入、越权、信息泄露等问题？
- [ ] **测试覆盖**：有没有对应的测试？关键路径覆盖了吗？
- [ ] **文档更新**：README、CHANGELOG 要不要同步更新？
- [ ] **兼容性**：会不会破坏已有的功能？是不是 breaking change？

#### 5.2.2 Review 的沟通技巧

**不好的 Review：**
> "这段写得不好，重写。"

**好的 Review：**
> "这里用 `for` 循环的话，每次都会触发渲染，建议改成 `computed` 缓存一下。
> 参考：[链接到相关文档]
> 如果你觉得有其他更好的写法，也可以讨论~"

区别在哪里？
- ✅ 说清楚"为什么不好"
- ✅ 给出建议的方案
- ✅ 提供参考资料
- ✅ 语气友好，留有余地

**记住：**
- Review 的是代码，不是人
- 对事不对人
- 可以有不同意见，可以讨论
- 最终决定权在维护者手里，但要尊重贡献者的劳动

#### 5.2.3 PR 合并时机

什么时候可以合并 PR？

- [ ] 至少有一个维护者 approve
- [ ] 所有 CI 检查都通过（lint、测试、构建）
- [ ] 没有未解决的讨论
- [ ] 文档同步更新了
- [ ] CHANGELOG 更新了（如果需要）

**小改动**（错别字、注释、文档）：
- 一个 maintainer approve 就可以合

**大改动**（新功能、重构、核心逻辑）：
- 至少两个 maintainer approve
- 需要充分讨论

### 5.3 版本发布

#### 5.3.1 语义化版本

推荐使用 [语义化版本（SemVer）](https://semver.org/lang/zh-CN/)：

主版本号.次版本号.修订号
│ │ │
│ │ └─ 修订号：bug 修复，向下兼容
│ └─ 次版本号：新增功能，向下兼容
└─ 主版本号：不兼容的 API 改动


示例：
- `v1.0.0` → 第一个正式版本
- `v1.0.1` → 修复了几个 bug
- `v1.1.0` → 新增了一些功能
- `v2.0.0` → 有不兼容的大改动

#### 5.3.2 CHANGELOG

每个版本都应该更新 `CHANGELOG.md`，记录这个版本的变化：

```markdown
# Changelog

所有重要的变更都会记录在这个文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]

### 新增
- 民族详情页新增语音朗读功能

### 优化
- 列表滚动性能优化，帧率提升 30%

### 修复
- 修复深色模式下图标颜色不对的问题

---

## [1.0.0] - 2026-06-29

### 新增
- 🎉 第一个正式版本发布！
- 56个民族百科介绍
- 民族分布地图
- 知识测验功能
- AI 问答助手
- 收藏功能
- 深色模式支持
5.3.3 发布流程
  1. 确定版本号：根据改动大小，确定是修订号、次版本号还是主版本号
  2. 更新 CHANGELOG：把 Unreleased 的内容移到新版本下面
  3. 更新版本号：修改 build-profile.json5、module.json5 中的版本号
  4. 提交代码：git commit -m "chore: release v1.1.0"
  5. 打标签：git tag v1.1.0
  6. 推送：git push && git push --tags
  7. 写 Release Note：在 GitHub 上创建 Release，详细介绍这个版本
  8. 构建打包：打出正式的 HAP/APP 包
  9. 发布上架：上传到应用市场

🎯 版本发布的核心原则：可追溯。

任何一个版本，都能找到：

  • 它包含了哪些改动
  • 对应的代码提交
  • 发布时间
  • 对应的安装包

🛠️ 核心实现

项目开源了，不代表就有社区了。

社区是需要运营的——就像种一棵树，不是把种子扔到土里就完事了，还要浇水、施肥、除虫。

6.1 社区运营的不同阶段

阶段 特征 重点工作
0 - 10 Star 只有你自己 打磨产品，写好文档
10 - 100 Star 有一些围观者 积极回应 Issue，鼓励第一个贡献者
100 - 1000 Star 有持续的贡献者 建立贡献者体系，完善流程
1000+ Star 有一定知名度 社区治理，长期规划

对应到「民族图鉴」的阶段目标：

  • 短期（3个月）：100 Star，5 个贡献者
  • 中期（6个月）：500 Star，20 个贡献者
  • 长期（1年）：1000+ Star，成为鸿蒙开发的经典学习项目

6.2 怎么推广你的项目

酒香也怕巷子深。好项目也需要让更多人知道。

6.2.1 内容推广

这是最有效、也最适合「民族图鉴」的方式——

我们已经有 100 篇技术文章了！这本身就是最好的推广素材。

可以做的：

  • 把文章发到技术社区：掘金、知乎、CSDN、InfoQ、华为开发者论坛
  • 每篇文章末尾加上项目地址，引导读者去 GitHub
  • 做一个"从零到一学鸿蒙开发"的系列专栏
  • 录视频教程，B 站、YouTube 同步发

优势：

  • 内容本身有价值，不是硬广
  • 吸引来的都是精准用户（想学鸿蒙开发的人）
  • 长尾效应，文章会持续带来流量
6.2.2 社区互动
  • 在相关的技术群里分享（但不要刷屏）
  • 回答别人的问题，顺便提到你的项目
  • 参与其他开源项目，互相引流
  • 组织线上分享、线下 Meetup
6.2.3 找 KOL 合作
  • 请技术大 V 帮忙推荐
  • 邀请行业专家 review 代码
  • 和相关的公众号、媒体合作

⚠️ 注意：推广的前提是产品本身过硬。

如果项目本身很烂，推广得越多，死得越快。

先把产品和文档做好，再考虑推广的事。

6.3 鼓励贡献的方法

有人愿意贡献代码，是开源项目最宝贵的事情。

怎么鼓励更多人贡献？

6.3.1 降低参与门槛
  • 把文档写清楚（README、CONTRIBUTING）
  • 标记 good first issue，给新手一个入口
  • 提供详细的开发环境搭建指南
  • 准备一些简单的任务，让新人容易上手
6.3.2 及时响应
  • Issue 尽量在 24 小时内回复
  • PR 尽量在 3 天内 review
  • 哪怕暂时没时间，也先说一声"收到，晚点看"

为什么重要？

  • 贡献者都是用业余时间来贡献的
  • 如果提交了 PR 一个月没人理，热情就凉了
  • 响应速度直接决定了贡献者会不会继续贡献
6.3.3 认可与感谢
  • 每一个贡献者，都要在 Release Note 里 @ 出来
  • 建一个 CONTRIBUTORS.md，列出所有贡献者
  • 在 README 里感谢贡献者
  • 定期做"贡献之星"之类的评选
  • 项目做大了，可以考虑寄周边、发小礼品

💡 人都是需要正向反馈的。

你感谢他，他开心，就会继续贡献。
你不理他，他下次就不来了。

这不是客套，这是基本的运营常识。

6.4 处理冲突与争议

有人的地方就有江湖。社区大了，总会有分歧、有争议、有冲突。

处理原则：

1. 对事不对人

  • 讨论代码、讨论方案，不要人身攻击
  • 不同意意见可以反驳，但要尊重对方
  • 禁止：辱骂、人身攻击、阴阳怪气

2. 技术问题，用数据和事实说话

  • 不要"我觉得"，要说"数据显示"、“测试表明”
  • 有争议的方案，可以做 A/B 测试，用结果说话

3. 维护者有最终决定权

  • 讨论可以充分，但最终总得有人拍板
  • 维护者对项目负责，所以最终决定权在维护者手里
  • 决定了之后，就按决定来，不要反复扯皮

4. 设定行为准则（Code of Conduct）

可以加一份 CODE_OF_CONDUCT.md，明确社区的行为规范：

# 社区行为准则

## 我们的承诺

为了营造一个开放、友好的社区环境，我们承诺：
- 每个人都可以不受骚扰地参与
- 欢迎不同背景、不同水平的人加入

## 我们的准则

✅ 欢迎的行为：
- 使用友好、包容的语言
- 尊重不同的观点和经验
- 耐心接受建设性批评
- 关注对社区最有利的事情

❌ 不欢迎的行为：
- 人身攻击、辱骂、侮辱性语言
- 骚扰、威胁、跟踪
- 公开发布他人的私人信息
- 其他不道德或不专业的行为

## 责任

项目维护者有责任：
- 明确可接受的行为标准
- 对不可接受的行为采取适当的纠正措施
- 删除、修改、拒绝违反本准则的贡献

## 举报

如果你遇到了违反本准则的行为，请联系项目维护者。

所有举报都会被保密处理。

🛠️ 核心实现

开源不是一时兴起，而是长期的事情。

7.1 维护者的时间管理

很多开源项目死掉，不是因为技术不行，而是因为维护者 burnout（ burnout = burnout burnout， burnout burnout）。

怎么避免 burnout？

1. 设定期望值

  • 不要期望自己能 7×24 小时响应
  • 告诉大家"我是用业余时间维护的，回复可能不及时"
  • 在 README 里写清楚预期响应时间

2. 学会说不

  • 不是每个功能都要加
  • 不是每个 PR 都要合
  • 不是每个 Issue 都要修
  • 你的时间和精力是有限的

3. 找帮手

  • 项目做大了，找几个靠谱的贡献者当 co-maintainer
  • 把权力下放，不要什么都自己扛
  • 培养接班人，不要做"公交车因子"为 1 的项目

💡 什么是公交车因子？

假设项目的核心维护者被公交车撞了，项目还能继续运转吗？

如果只有一个人懂，那公交车因子就是 1，很危险。

好的项目，公交车因子至少是 2-3 个。

7.2 持续迭代的节奏

不要追求"完美的版本"——没有完美的版本，只有不断迭代的版本。

推荐的节奏：

  • 小版本（修订号）：随时发，bug 修好了就发
  • 中版本（次版本号）：每个月或每两个月发一个
  • 大版本（主版本号）：半年到一年发一个

「民族图鉴」的迭代计划示例：

版本 时间 核心内容
v1.0 2026.06 第一个正式版本，核心功能
v1.1 2026.08 新增社区贡献的功能、bug 修复
v1.2 2026.10 性能优化、体验改进
v2.0 2027.01 架构升级、鸿蒙 7 新特性深度整合

7.3 归档与传承

如果有一天，你真的不想维护了——

这很正常。没有人有义务永远维护一个开源项目。

你可以：

  1. 在 README 里说明：

    这个项目不再维护了。

    如果你想接手维护，可以 fork 过去继续做。

    推荐这些还在维护的 fork：…

  2. 找接手的人：

    • 在社区里问有没有人愿意接手
    • 把仓库权限转给靠谱的人
    • 或者归档，让项目停在那里

  3. 把项目交给组织：

    • 如果项目足够重要，可以交给开源社区组织
    • 比如 Apache 基金会、Linux 基金会等

但请不要：

  • 一声不吭就消失
  • Issue 和 PR 堆着不处理
  • 让后来的人不知道项目是什么状态

🎯 好聚好散，也是开源的一部分。

你来的时候，带来了一个好项目。

你走的时候，也要给社区一个清楚的交代。

📝 本章小结

最后，让我们为「民族图鉴」制定一个开源路线图。

阶段一：准备阶段（第1-2周）

  • 代码清理：移除敏感信息、移除冗余代码
  • 整理仓库结构：按推荐结构调整
  • 选择开源协议：MIT License
  • 写 README：项目介绍、快速开始、功能特性
  • 写 CONTRIBUTING：贡献指南
  • 准备截图：首页、详情页、列表页等
  • Lint 检查：确保代码没有明显问题

阶段二：正式开源（第2-4周）

  • 创建 GitHub 仓库
  • 推送代码
  • 发布 v1.0.0
  • 写第一篇官宣文章
  • 发到技术社区：掘金、知乎、华为开发者论坛
  • 建立 Issue 模板和 PR 模板
  • 配置 CI：自动 Lint、自动构建

阶段三：社区建设（第1-3个月）

  • 积极回应 Issue 和 PR
  • 标记 good first issue，引导新人参与
  • 建立贡献者名单
  • 定期发布小版本
  • 收集用户反馈，迭代产品
  • 做几期"贡献者专访"
  • 争取达到 100 Star

阶段四：生态发展（3-6个月）

  • 建立 co-maintainer 团队
  • 组件库抽离，独立发布
  • 和其他鸿蒙项目建立联系
  • 参与鸿蒙生态活动
  • 争取达到 500 Star
  • 成为鸿蒙开源社区的知名项目

阶段五：长期运营（6个月以上）

  • 定期发布版本，保持项目活力
  • 建设文档站，提升学习体验
  • 组织线上/线下分享活动
  • 探索商业化的可能性（如果合适）
  • 争取达到 1000+ Star
  • 成为鸿蒙开发的标杆学习项目

🔗 相关链接

100 篇文章，到这里就全部结束了。

从第 1 篇的"鸿蒙是什么"，到第 100 篇的"怎么开源一个项目"——

我们一起走完了一个完整的闭环：

学习技术 → 做项目 → 优化项目 → 工程化 → 上架 → 运营 → 开源

这不仅仅是一个技术学习的过程，更是一个"从想法到产品"的完整旅程。

一些真心话

做开源项目，和做商业项目不一样。

商业项目是为了赚钱，KPI 是营收、是 DAU、是转化率。

而开源项目，更多的是因为热爱——

  • 热爱技术
  • 热爱分享
  • 热爱"把一件事做好"的感觉

在这个过程中，你会收获：

  • 📈 技术能力的提升
  • 👥 认识一群志同道合的朋友
  • 🏆 个人品牌和影响力
  • 😊 纯粹的、创造的快乐

当然，也会有辛苦、有委屈、有想放弃的时候。

但回过头来看，那些你花了很多时间、踩了很多坑、最后做成了的事情——
往往是最值得回忆的。

给你的建议

如果你也想做一个开源项目：

1. 从解决自己的问题开始
不要为了开源而开源。先想想：你自己有什么痛点？有什么工具是你自己需要的？
从自己的需求出发，做一个你自己会天天用的工具。
这样，哪怕没有人用，至少你自己用得上，不会亏。

2. 小步快跑，持续迭代
不要追求"完美了再发布"——完美是不存在的。
先发布一个最小可用版本，然后根据反馈慢慢改进。
0.1 版本 > 完美的 1.0 版本（因为后者永远不会发布）。

3. 享受过程，不要焦虑
不要天天盯着 Star 数看，不要焦虑"为什么没人用"。
把注意力放在"把事情做好"上，而不是"要有多少人关注"上。
慢慢来，比较快。

关于「民族图鉴」

「民族图鉴」这个项目，最初只是一个用来教学的示例。

但随着 100 篇文章的推进，它慢慢变得完整、变得丰富、变得真的像一个产品了。

希望它能成为：

  • 鸿蒙开发者的入门教材
  • 鸿蒙开源项目的样板
  • 民族文化传播的小小窗口

如果你看到了这里，如果你觉得这个项目还不错——
欢迎你参与进来，不管是提 Issue、提 PR，还是只是点个 Star。

开源的世界，因为有你，才更精彩。

**我们江湖再见。**👋

「民族图鉴」100篇鸿蒙开发技术文章 · 完

感谢你的阅读，祝你的代码永远没有 bug。

# harmonyos # 开源 # 华为
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

基于鸿蒙OS开发打飞机小游戏（25）-暗夜降临技能

avatar 人工智能6S服务平台
cover

基于鸿蒙OS开发打飞机小游戏（29）-模拟器调试与性能优化

avatar 人工智能6S服务平台
cover

基于鸿蒙OS开发打飞机小游戏（28）-HUD与界面设计

avatar 人工智能6S服务平台