Immutable. This exact content is served forever at /api/v1/blob/5ace90a50ffb3b81.
--- name: github-readme-cn description: 中文开源项目的 README 与仓库门面优化。当用户说"我的开源项目没人看""README 怎么写""GitHub 仓库怎么优化""帮我写 README""项目主页太丑""怎么让别人愿意 star"时使用。基于对 15 个近期高增长仓库的实测数据给出可执行建议，同时明确说明哪些是相关性、哪些无法验证——不承诺涨星。 metadata: author: sanhuang520-ship-it category: documentation tags: documentation, git, optimization, chinese --- # GitHub 中文项目门面优化 **先说清楚这个技能不做什么：它不能让你的项目火。** 下面的建议来自对 15 个近期高增长仓库的结构实测。这些是**相关性，不是因果**—— 我能测到"12/15 首屏有图"，但测不到"因为有图所以火"。真正决定传播的是**有没有人替你转发**， 而那个变量不在 README 里。 把门面做好的意义是：**当流量真的来的时候，不至于漏掉。** 仅此而已。 ## 什么时候用 写或重写开源项目的 README、仓库描述、topics；项目做完了没人看想找原因； 准备投稿到社区/周刊之前的自查。 --- ## 第一步：先问清楚三件事 1. **仓库地址**（有的话直接看现状，没有就问定位） 2. **目标读者是谁**——中文开发者？特定行业？海外？决定语言和例子 3. **这个项目和同类比，凭什么选它**——答不上来的话，README 写得再漂亮也没用 > ⚠️ 用户说"帮我优化 README"时，**不要直接开始写**。 > 先看他现在的 README 和仓库，指出具体差在哪，再动手。凭空写出来的通常是套话。 --- ## 首屏是唯一重要的位置 GitHub 上不滚动能看到的大约是 **README 前 15 行**。绝大多数人只看这一屏。 ### 实测：15 个高增长仓库的首屏 | 特征 | 命中 | 说明 | |------|------|------| | **首屏有图** | **12/15** | 最普遍的一条 | | 首屏有徽章 | 11/15 | shields.io | | 首屏有安装命令 | 4/15 | 少见，但对工具类很有用 | | 首屏能点到 demo | 3/15 | 少见，做了就是差异化 | | 标题用中文 | 2/15 | 即便是中文项目也多用英文名 | **中位数参考**：README 15 KB · 图片 10 张 · 仓库名 14 字符 · topics 9 个 ### 首屏该有的东西，按顺序 ```markdown <div align="center"> <img src="真实产品截图或效果图" width="100%"> # 项目名 **一句话说清楚它给你什么**（不是"这是一个基于 XX 的 YY 框架"） [徽章] [徽章] [徽章] [🌐 在线体验] · [📋 文档] · [📸 效果图] </div> > **和同类比有什么不一样** > ① …… ② …… ③ …… ```bash 一行就能跑起来的命令 ``` ``` --- ## 关于首屏那张图 **用真实产出，不要用设计稿或抽象插画。** 如果你的项目输出是可视的（网页、图表、CLI 界面、渲染结果）， 直接 headless 截图，比任何设计稿都有说服力： ```bash "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --headless --disable-gpu --hide-scrollbars \ --force-device-scale-factor=2 --window-size=1400,900 \ --screenshot=shot.png "https://你的页面" ``` **多张拼成一条横幅**比单张更能体现"有内容"。PNG 转 WebP 通常能省 80%+ 体积。 ⚠️ **截图前务必确认它真的反映差异**。常见翻车：用 `?theme=xxx` 之类的 URL 参数截 8 张"不同主题"， 结果参数根本不生效，8 张图 md5 完全相同。**截完对一下哈希**。 ⚠️ **样张里不要编数据**。演示文案里写"测试 200 组样本，准确率 91%"这种， 读起来像真实结果——如果你没测过，这就是造假。 --- ## 命名与描述 | 项 | 建议 | |----|------| | **仓库名** | 中位数 14 字符。`awesome-chinese-ai-tools`（24）就偏长，且带了已经不准的词 | | **仓库描述** | GitHub 搜索结果里显示的就是这句。放数字和差异点，别放形容词 | | **topics** | 上限 20 个。**用目标用户真正会搜的词**，不是你觉得贴切的词 | > topics 是最容易被忽略的一环。检查方法：去 GitHub 搜你希望被搜到的词， > 看排前面的仓库都打了哪些 topic。如果你的词和他们完全不重合，就是搜不到的原因。 > ⚠️ **用英文词搜，也打英文 topic。** 2026-08-28 实测：`元素周期表` 的前 5 名 > 没有一个是周期表项目，`互动学习 物理 化学` 返回 0 结果；换成 > `periodic table interactive` 则前 5 全部相关。中文项目可以有中文说明， > 但**别指望中文关键词把人带过来**。（数据见 `references/measured-data.md` 第四节） --- ## 自查清单 跑一遍，每条都能答"是"再发出去： - [ ] 不滚动能看到：图、一句话价值、怎么开始 - [ ] 那句话说的是**读者得到什么**，不是**技术栈是什么** - [ ] 首屏的图是真实产出，不是示意 - [ ] 所有内链都点得开（**批量验证，别靠肉眼**） - [ ] README 里的数字和实际一致（数量、版本、日期） - [ ] 仓库描述、topics、社交分享图都是当前定位，不是上一版 - [ ] 如果项目会变（收录数、版本），**README 由脚本生成**，不靠手写 - [ ] 写死的结论**定期复测**——工具会变。（本项目就遇到过：`npx skills add` 的落盘路径在 CLI 升级后变了，旧结论没错但已经不完整） 最后一条是经验：手写的数字必然过时。见过写着"114 个"实际 116 个的， 也见过分享图还停留在半年前的定位。 --- ## ⚠️ 关于"涨星打法"，几个我验证不了的事 做这个技能时我实测了 15 个高增长仓库，有三件事必须说明： **1. 幸存者偏差无法消除** 只能看到火了的。用同样结构但没人看的仓库有多少，GitHub 不会告诉你。 **2. 传播源头测不到** 我尝试拉这些仓库的 stargazer 时间线（想看星是一夜爆发还是持续增长）， **全部返回 404**——普通 token 读不到别人仓库的这个数据。 所以**无法区分"README 好"和"某个大号转发了"**。这是最关键的因果问题，我没有答案。 **3. 作者本身的影响力是重要变量** 实测 15 个高增长仓库作者的粉丝数： ``` 0–50 粉（素人） 3 个 50–500 粉 5 个 500–5000 粉 7 个 5000+ 粉（大 V） 0 个 ``` **没有一个是大 V，但 12/15 有超过 50 个粉丝。** 素人爆火真实存在（有 47 粉丝拿到 5000+ 星的案例），但属于少数。 **所以：任何声称"照着做就能火"的教程，如果它没有上面这些数据，它在猜。** --- ## 这个技能不做的事 1. **不做刷星、互 star、买量**。换来的是死星，会污染你判断真实认可的能力。 2. **不承诺结果**。上面全部是相关性，做到了不保证有人来。 3. **不替你编内容**。README 里的数字、效果、案例必须是真的，我不会帮你写没验证过的东西。 4. **不做英文项目的本地化建议**——目标读者是海外的话，这套中文语境的判断不适用。 --- ## 参考 `references/measured-data.md` —— 15 个仓库的完整实测数据、测量方法、可复现的脚本思路。