GitHub 默认搜索只搜三个地方——15 个关键词、3 轮中位数的排名实验

最近我想验证一个很具体的假设：GitHub 的默认搜索，到底看不看 README？

起因很朴素。我们维护一个数字商品方向的开源仓库，在几个细分词上，仓库名、描述和内容都比排在前面的仓库更匹配，但默认搜索就是搜不到；反过来，一些 star 更少、更新更慢的仓库却排在前面。于是我干脆做了一次对照实验：只改元数据，不改代码，然后在 24 小时内跑 3 轮、每轮间隔 30 分钟，取中位数。

先说结论：GitHub 默认搜索主要看仓库名、About 描述和 Topics；README 是另一套入口，只有显式用 in:readme 才会明显读到正文。 同一个关键词 发卡寄售，改前默认搜索只有 4 条结果，in:readme 有 1,504 条——两者不是一个量级。把精确短语放进 About 的前 60 个字符，比在 README 里堆十遍更有效。

1. 默认搜索到底搜什么

我一开始也以为 GitHub 搜索会像 Google 一样读 README。实际测试下来，默认搜索（Best match）更像是在做“仓库元数据匹配”：

• 仓库名；
• About 描述；
• Topics（只接受小写字母、数字、连字符）；
• 以及 stars、更新时间、issue/PR 活跃度等 best match 信号。

README 是另一套入口：只有加 in:readme 才会进正文索引。这个区分很关键——很多人把关键词全塞进 README，默认搜索根本读不到；而 About 只有 350 字符，前 60 字符又是搜索结果里最容易被看到的，值得单独设计。

这不是 GitHub 官方公布的完整排序公式，只是我在这次实验里观察到的稳定规律。stars 和活跃度仍然会影响 best match，所以下面的数据不能理解成“改了描述就一定第一”。

2. 怎么测：15 个词、3 轮、中位数

测量方法很简单，但有两个细节必须做对：

1. 同一个词至少跑 3 轮，每轮间隔 30 分钟以上，取排名中位数；单次快照会骗人，今天 #3、明天掉出前 100 是常态。
2. 用 per_page=100 拉满前 100 条，再在结果里找自己的仓库；不要只看第一页。

脚本用 gh 的 API，不需要额外依赖：

import json
import subprocess
import time

QUERIES = [
    '发卡寄售', '24 小时发卡平台', '寄售网', '数字商品寄售', '虚拟商品寄售',
    '卡密寄售', '数字商品交易平台', '卡密自动发货', '卡密平台', '发卡平台',
    '自动发卡', '发卡', '虚拟发卡', '发卡网', '发卡系统',
]

for q in QUERIES:
    r = subprocess.run(
        ['gh', 'api', '--method', 'GET', 'search/repositories',
         '-f', f'q={q}', '-f', 'per_page=100'],
        capture_output=True, text=True,
    )
    if r.returncode != 0:
        print(q, 'API_ERROR', r.stderr.strip()[:200])
        time.sleep(2)
        continue
    data = json.loads(r.stdout)
    items = data.get('items', [])
    rank = next(
        (i for i, item in enumerate(items, 1)
         if item['full_name'] == 'OWNER/REPO'),
        None,
    )
    print(q, data.get('total_count'), rank or 'not in top100')
    time.sleep(1)  # 避开 GitHub search 的二次限流

改动后 10–15 分钟跑第一轮，之后每隔约 30 分钟跑一轮，第三轮在当天 20:43 完成。下面的“改后”全部是三轮中位数，不是最好那一次。

3. 改了什么：只动元数据，不动代码

改动只有三处：

About 描述。 总长约 240 字符，前 60 字符放最强的两个精确短语，后面接一句人话说明。没有把十个词排成关键词清单——那样读起来像 spam，也容易被判定低质。

Topics。 补了 5 个英文检索词（如 faka-platform、card-key-marketplace、digital-goods-consignment），同时删掉几个泛词（国家名和通用词）。Topics 对中文查询基本无效，主要服务英文检索和主题识别。

README。 H1 改短，加了一张“常见叫法”表，把用户可能搜的词和平台叫法对应起来；再加了几条 FAQ 和一段英文摘要。README 主要是给 in:readme 和人类看的，不是默认搜索的主战场。

没有买 star，没有刷 issue，没有批量关注。仓库本身有约 300 star，这是实验的控制变量：排名变化发生在元数据改动后的 10–15 分钟内，而不是 star 突增之后。

4. 结果：零结果的细分词进了第一，强词保持

改前 → 改后（2026-10-19，三轮中位数）：

关键词	改前结果数	改前排名	改后中位数
发卡寄售	4	未进前 100	#1
24 小时发卡平台	0	未进前 100	#1
寄售网	8	未进前 100	#1
数字商品寄售	4	未进前 100	#1
虚拟商品寄售	2	未进前 100	#1
卡密寄售	4	未进前 100	#2
数字商品交易平台	52	#2	#2（保持）
卡密自动发货	48	#8	#8（保持）
卡密平台	114	#17	#7
发卡平台	392	#48	#17
自动发卡	609	#66	#36
发卡	3,108	未进前 100	#88
虚拟发卡	142	未进前 100	#13
发卡网	516	未进前 100	#25
发卡系统	747	未进前 100	仍未进前 100

英文侧（默认搜索，非 in:readme）：

• faka platform：改前默认 5 条、未进前 100 → 改后 #3；
• digital goods consignment：改前 0 条 → 改后 #1；
• virtual card code marketplace、card key auto delivery：仍未进前 100。

2026-10-20 我又跑了一次单轮复核：15 个中文词的排名与上表一致（发卡 #88 → #89，其余不变），英文侧也不变；结果数只增加了几条（有新仓库进来）。这说明这组数据至少隔天可复现，不是单日偶然。

最直观的规律：结果数只有个位数甚至 0 的细分词，排名变化最快；几百上千条的泛词，提升慢得多。 如果你要做冷启动，先找那些“搜得到但没人认真做”的词，而不是一上来冲大词。

5. 没做到的，以及一个真实的取舍

这次实验不是全线第一，有三个失败项值得写出来：

1. 发卡系统 仍未进前 100。 这个词有 747 条结果，前排是几个 star 很高、更新很勤的老仓库，靠改 About 追不上。它不在这次的目标里，我也没有为它继续堆词。
2. 虚拟发卡 #13、发卡网 #25。 都从“未进前 100”大幅改善，但没进前 10；泛词需要更长时间的活跃度和外部链接，不是一次元数据改动能解决的。
3. 英文侧有一个取舍。 改前 About 的英文尾是 China digital goods marketplace，默认搜索 #1；为了覆盖 faka platform，我把英文尾换成了 faka platform，结果前者从 #1 掉到无结果。About 只有 350 字符，英文短语最多放 2–3 个，换词就是换覆盖面，不存在全都保住。

还有一个必须承认的边界：GitHub 的 best match 会漂移。同一周内，同一个词的单次快照可能从 #3 掉出前 100；所以本文所有结论都基于三轮中位数，而不是某一次截图。

6. 可复用的五条

1. About 前 60 字符放最强精确短语，后面写人话；不要排成关键词清单。
2. Topics 放 5 个英文检索词，不堆拼音；国家名和泛词换成品类词。
3. README 写给 in:readme 和人类看，默认搜索不吃正文；H1 短、加“常见叫法”表和 FAQ。
4. 同一个词跑 3 轮取中位数，每轮间隔 30 分钟以上；单次快照只当参考。
5. 不买 star、不刷 issue；排名会漂移，改动后 1–2 周再复查一次，别在发布当天反复改 About。

这次实验没有让所有词都第一。它只是把几个零结果的细分词做到了 #1，把原来的强词保持住，并且让我确认了一件事：在 GitHub 上，把词放对地方，比把词写多更重要。