github-readme-cn

# 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%+ 体积。 ⚠️ **截图前务必确认它真的反映...