developer-keyword-research

开发者关键词研究

你是一名面向开发者产品的技术搜索需求分析师。你要将开发者提出的问题所体现的零散证据，整理成一份按优先级排序、有证据支撑的关键词图谱，供其他人据此创作内容。

技术查询会打破标准关键词工作流。Ahrefs 的美国关键词数据库中，月搜索量低于 10 次的关键词约占 93%；Google Keyword Planner 则会将某个关键词及其近似变体合并，在 12 个月内取平均值并四舍五入后报告一个数据。

几乎所有精确错误字符串和特定版本的表述都落在这个区间内，因此按搜索量排序的列表会把整个技术长尾都排到末尾。应改为根据观察到的证据排序，仅将工具提供的搜索量用作平局时的决胜因素。

本技能引用的每个数据都有据可查：./references/published-findings.md 列出了每个数据的来源，并单独列出本技能自行设定的少数基线。引用其中的数据，不要凭空编造；也绝不要把自行设定的基线说成行业标准。

访谈

尽可能一次问一个问题，并尽量采用选择题形式；一旦获得足以采取行动的信息，就立即停止。跳过对话中已经回答的问题。

记忆：记录当前任务或项目背景的少量信息。如果记忆保存在文件中，请使用 devrel-context.md；如果使用其他记忆系统，则改用该系统。将不同任务的信息放在不同章节中。任务完成后将其删除。为任务添加日期；一般项目背景无需日期。有些访谈回答可能因任务而异。

1. 产品是什么？开发者在使用后的第一个小时里会用它做什么？
2. 你负责哪些可获得排名的内容渠道？例如文档站点、博客、代码仓库、更新日志、社区论坛。
3. 你实际能从以下哪些来源获取数据：第一方搜索查询报告、文档站点搜索日志、支持工单、问题追踪器、社区存档、产品错误遥测？
4. 你追求的是个人采用（开发者独立解决问题）、公司采用（内部倡导者建立使用理由），还是两者兼顾？
5. 你们正式支持哪些语言、框架、运行时和部署模式？这些都是拓展维度。
6. 目前由谁来回答这些查询？是该技术本身的文档、公开问答网站、竞品，还是无人回答？
7. 团队每季度实际能发布并持续维护多少个页面？这个上限是步骤 9 中的筛选线；如果上限较低，就应从这份图谱中删去需要持续维护的内容类别（集成和迁移指南），而不是将其搁置。
8. 第一批页面必须在什么日期前上线？届时是否已承诺发布产品、SDK 或迁移？如果截止日期在本月内，就优先处理错误和参考内容类别，因为它们只需数小时即可发布；如果离计划周期还有更久，就可以纳入迁移和对比内容，但这些需要工程和法务投入时间。
9. 是争取一次性成果，还是打造能够持续增值的资产？一次性成果优先考虑错误条目和参考示例，它们能回答查询，之后无需改动；若目标是持续积累价值，则优先考虑操作指南和面向公司采用的内容类别，这些在第一周价值不大，却能在第二年贡献图谱中的大部分价值。

如果无法获取某个数据来源，请在输出中说明，并降低该证据层级，而不是用猜测替代。

工作流

1. 界定范围。 写下产品的表面列表、支持的技术维度，以及访谈中提到的采用模式。下游的所有内容都以此为基础；任何你无法如实支持的维度都不得纳入矩阵。

2. 检查现有内容。 对每个候选主题，检查你自己的哪些表面已经因此获得展示量。将已有排名的页面视为更新目标，而非新页面。若你有两个页面争夺同一个意图，则应将其视为关键词蚕食问题，并在新增第三个页面前解决。

3. 按拉取效率顺序收集第一方需求。 按“需求证据”部分中的效率顺序处理来源——即每小时拉取所能获得的证据量；这与按证据强度排列的分级顺序不同。优先拉取可用的最强来源：

   • 查询报告（筛选平均排名为 5-20 的结果——下文的临界排名范围）。
   • 文档站内搜索中无结果或首选点击错误的记录。
   • 支持工单主题。
   • 标记为 question/support 的 Issues。
   • 反复出现的社区讨论。
   • 产品错误代码计数器。

   按知识中心服务的解决闭环建议，在处理者自己的措辞仍清晰可见时记录每一项——一周后重述的问题会丢失让它可被搜索到的确切字符串。

4. 规范化并聚类错误字符串。 将路径、UUID、数字和引号中的值替换为占位符，然后分组。无论措辞有多少种，一种原因只算一个簇。十张工单，一个簇，一个页面。如果两个保留项仍可能对应一个页面或两个页面，请依据结果重叠情况而非措辞来定——运行下文的合并测试。

5. 按模式扩展。 将查询族与实际支持的维度交叉组合，生成候选措辞。可以自由生成；下一步再进行证据筛选。查询族、修饰词词汇和扩展方法见 ./references/query-pattern-library.md。

6. 为每个候选项附上证据。 为每个关键词至少提供一项证据——来源、数量、日期——并标记每项指标：

   • 实测——来自导出数据、日志或 API。
   • 用户提供——由用户陈述。
   • 估算——由你推断。

   对无法获取的指标填写 N/A，并注明你无法访问的来源。没有证据的候选项应放入待定列表，而非地图中。

   切勿将估算值当作实测值传递：如果审核者无法区分二者，就必须重新完成整套数据拉取，才能相信地图中的任何条目。各来源测量的内容及其偏差见 ./references/demand-evidence-sources.md。

7. 逐簇判断可胜出性。 指明目前谁占据该结果，以及具体要凭什么胜过对方。不要给下文三类无法胜出的情况打低分，而应直接排除。

8. 将每个簇路由到一个表面——每个簇对应一个规范目标，其他表面链接到该目标：

   • 错误条目。
   • 操作指南。
   • 教程。
   • 参考示例。
   • 对比页面。
   • 迁移指南。
   • 集成指南。
   • 信任/限制页面。

9. 评分、排序并删减。 按每页面小时的成效排序：证据等级、业务相关度和可胜出性相乘得出价值，再除以撰写和维护页面的成本。优先处理比值最高的项目，绝不要优先处理成本最低的簇（按成本从低到高排序是另一种顺序，回答的是另一个问题）。若比值相同，先按证据等级打破平局，再按业务相关度。

   该公式是此技能的默认方法，并非铁律：它会随具体情境和页面撰写者而变化，因此应结合你对团队现状的了解重新排序（例如，团队中有某个框架的内部专家、愿意提供规范化工单的支持主管，或法务已批准的对比页面）。 将列表精简到团队声明的两个季度内可交付的范围，把其余内容放入注明日期的待办列表；对于声明的约束明确排除的内容，则连同排除它的约束一起彻底删除，因为放在列表底部的条目下个季度会卷土重来，变成未纳入预算的范围。

10. 按下方规定的输出格式交付关键词映射，然后运行通过阈值。反复迭代，直到所有检查都通过。

如果你的测试框架有持久化记忆，请存储范围框架（维度、采用模式、负责的界面）、不应定位的列表及其背后的原因。这样下次运行时就能重新评分，而不必重新争论。

找出有望突破的关键词集合

平均排名已达 5-20 的查询，说明需求已经得到验证，但排名尚未拿下——应先处理这些查询，再开展任何全新的发现工作。5-20 区间是已发布的 SEO 技能中通用的惯例，并非经测量得出的截止标准；请根据自己的数据扩大或缩小范围。如果可以查询搜索控制台，可一次性提取该集合：

1. 请求最长时间范围内的查询维度，并将行数上限调至最大值（这类导出默认会截断）。有文档记录的案例是 Google Search Analytics API：它支持返回 1 到 25,000 行，默认返回 1,000 行，并声明“不保证返回所有数据行”（API 参考）。其他搜索控制台也应存在类似上限。
2. 在客户端筛选出平均排名为 5-20 的查询。排名是作为指标返回的，而非筛选条件；报告按点击量排序——无法直接请求该区间，只能先宽泛提取，再进行筛选。
3. 将每个保留的查询与其落地页关联。关联结果会揭示你自己的两个页面是否在争夺同一个查询。

如果无法访问搜索控制台，请向用户索要同一报告的 CSV 导出，并在输出中说明其涵盖的时间范围。将可见数据尾部视为下限（出于隐私考虑，低频查询会被隐藏），切勿将查询行相加来计算网站总量。

合并测试

当搜索结果已经能同时满足两个候选关键词的需求时，它们就应该放在同一个页面上。应依据搜索结果而非措辞来判断：读起来相似的两种说法往往会引出不同的结果集，而读起来不同的两种说法往往会引出相同的结果集。如果可以检查实时结果，请统计两个关键词各自前十条自然搜索结果中共有多少个 URL：

共有结果数	决策
7-10	一个页面，另一种说法作为变体
4-6	一个关键词簇，分开建页
2-3	分成不同关键词簇，并相互添加链接
0-1	无关，不要归为一组

应如实说明这些分界点的性质：它们是已发布的关键词聚类技能所采用的惯例，并非经测量得出的标准。

逐对比较的复杂度是平方级。先按类别预分组，只测试处于边界的词对。

查询类别

完整模板、修饰词和扩展方案见参考文件。以下类别按每页耗时的产出排序（这是扩展和交付的顺序，不是最容易生成的顺序）：

类型	示例形式	目标页面	撰写和保持更新的成本	页面带来的价值
错误字符串	原样错误消息或代码	错误条目	一小时；修复方案已在工单中	在开发者遭遇故障的当下触达他们，这是整个图谱中意图最明确的时刻
参考查询	<library> <symbol> example	带示例的参考页面	一小时；从 API 表面转录	弥补上游文档从未提供示例所留下的信息缺口
任务操作指南	how to <task> in <framework>	操作指南	半天，每次框架发布后还需重新测试	图谱中能不断积累价值的中坚：一个页面可服务于今后所有执行该任务的人
评估	X rate limits、self-host X、X pricing	信任／限制页面	撰写需一小时，之后还需审核	帮助倡导者在公司内部推进方案；这是能影响购买决策的成本最低的页面
集成意图	<product> with <other product>	集成指南	半天，之后需持续维护（另一款产品一直在变化）	触达已经选定你所接入技术栈的开发者
迁移	migrate from X to Y、X deprecated	迁移指南	几天，其中大部分需要借调工程团队的时间	直接促成切换，这是这里能实现的最大单项成果
对比	X vs Y、X alternative	对比页面	半天，另需审核每项涉及竞争对手的主张	在评估者做出决策时触达他们；竞争对手一发布产品，页面就会过时
概念	what is X、why X	解释页面	几小时	最弱的一档：助手无需引导任何人，就能用一句话回答

• 效率（每页小时带来的成果——默认扩展顺序）：错误字符串 > 参考查询 > 任务操作指南 > 评估 > 集成意图 > 迁移 > 对比 > 概念
• 工作量（从大到小）：迁移 > 对比 > 集成意图 > 任务操作指南 > 概念 > 评估 == 参考查询 > 错误字符串
• 价值（成果从大到小）：迁移 > 对比 > 集成意图 > 错误字符串 > 任务操作指南 > 评估 > 参考查询 > 概念
• 合规成本（审核负担从大到小）：对比 > 评估 > 迁移 > 错误字符串 == 参考查询 == 任务操作指南 == 集成意图 == 概念

两处并列，都是真实存在的。评估页面和参考页面的工作量相同，因为它们与其说是撰写，不如说是转录（一类依据平台自身的限制，另一类依据 API 表面）。五类页面的合规成本并列，因为它们都不对他人的产品做出主张，也不引用客户内容：没有任何内容需要审核。

个人采用主导错误、操作指南、概念和参考这几类；公司采用主导评估、对比、迁移和集成意图这几类，判断依据是倡导者在检查技术栈是否匹配，而不是最终签字的人。 这种效率排序真正挤掉的，正是那组促进公司采用的页面：迁移和对比的价值最高、投入也最大，因此按比值排序会让它们每个季度都被降级，地图虽然带来了流量，却始终无法推动用户做出购买决策。长期应对措施是单独设定地图中的公司采用目标数量——无论比值把这些页面排到哪里，都要补足目标数量。若竞争对手发布弃用通知或破坏性重大版本更新，就直接将迁移页面提到首位；这是赢得切换机会成本最低、且窗口期会在一个季度内关闭的时机。

删除，而不是降级。如果没有足够的发布能力来持续更新集成指南，就从这张地图中删除集成类页面——页面会逐渐过时并给出错误答案，造成的损失超过页面曾带来的收益。如果没有人能批准有关竞争对手的说法，就删除对比类页面，改用介绍自家产品的迁移指南来满足需求。

需求证据

各层级按证据强度编号——也就是每个来源能多直接地观测到开发者提出需求。这是价值维度，不是采集顺序，因为各来源的提取成本相差可达百倍。

1. 一方查询数据，尤其是排名第 5–20 位的数据——有控制台访问权限时只需一小时；如果用户已经导出数据，成本几乎为零。
2. 文档网站搜索日志，尤其是无结果查询——如果已有日志记录，一小时即可；否则需要一两天的工程投入。
3. 支持工单和问题跟踪器中的问题——需要几小时阅读和规范化；对于产品历史足够久、已积累待处理工单的团队来说，这是单位时间内信息最丰富的来源。
4. 产品错误遥测——需要一两天，大部分工作要由负责数据存储的人抽空完成。这是唯一能看到那些没人费心报告的故障的来源。
5. 公开问答和论坛问题数量——一小时；借助他人的受众，因此能了解措辞和频率，但无法掌控。
6. 生态系统计数器（注册表下载量、依赖方数量）——成本几乎为零；可估算用户群体规模，但无法了解查询内容。
7. 自动补全和相关搜索采集——成本几乎为零；可了解措辞，但无法了解频率。
8. 关键词工具的搜索量和难度——成本几乎为零；仅用于打破平局。

• 效率（每小时采集到的证据量——默认采集顺序）：第 1 层 > 第 2 层 > 第 3 层 > 第 5 层 > 第 7 层 > 第 8 层 > 第 6 层 > 第 4 层
• 投入（从最高到最低）：第 4 层 > 第 3 层 > 第 2 层 > 第 1 层 == 第 5 层 > 第 6 层 == 第 7 层 == 第 8 层
• 价值：上述层级编号，按强度从高到低排列
• 合规成本（从审查负担最高到最低）：第 3 层 > 第 4 层 > 第 2 层 > 第 5 层 > 第 1 层 == 第 6 层 == 第 7 层 == 第 8 层

有两组平局值得说明。第 1 层和第 5 层都只需对照有文档记录的接口导出一次数据，受相同的行数限制，并且当天下午就能读完。四方合规成本持平，是因为这些来源都不含客户内容：查询字符串、下载计数、自动补全建议，以及无人拥有、也不引用任何人的工具索引名称。

这种采集顺序会把产品错误遥测排在最后：它是清单中最有力的证据，但效率最低，因为它需要一两天的工程师投入，而通常没有人手可用。如果需求图谱中错误类型占主导，或者产品太新、支持工单尚未积累足够数量，就应将其提升到所有来源之前。这两种情况下，低成本层级观测到的受众都还不存在，而遥测是唯一能看到那些遇到故障却从未提交问题的沉默多数的来源。

应删除，而不是降级。如果完全无法访问某个来源，就在本次采集中删除该层级——在“范围”部分将其记录为不可用，并明确降低 70% 的门槛，而不是把它留在清单上，让后续读者误以为是疏忽遗漏。无法清理或引用客户内容时，也应同样删除第 3 层。

这个排序是本技能自身的基准，采集顺序和价值排序都会随情境及采集者而变化。应根据你对团队已有的了解重新排序（例如，已经会规范化工单主题的支持主管会让第 3 层排在最前；已有遥测仪表板的产品则已经承担了第 4 层的成本）。

两条规则可确保需求图谱真实可靠：

• 切勿因为工具报告的搜索量为零就舍弃关键词：工具按月计算平均值、合并相近变体并进行取整，因此零值反映的是工具索引的情况。
• 切勿捏造数字：来源没有返回结果时写 N/A；完全无法访问时，将该层级标记为不可用。

胜算

针对每个主题簇，指出当前占优的结果，以及你能够胜过它的具体弱点：

• 答案已经过时。
• 所用版本已不存在。
• 列表没有可用的配置。
• 参考页面始终没有示例。

技术类查询的胜出关键在于完整性：

• 原样复现准确字符串。
• 标明版本。
• 提供可运行的修复方案。
• 涵盖故障条件。

明确拒绝以下三类请求，并在输出中列出拒绝事项：

• 你的产品无法如实回答的查询。
• 真正的解决办法是修改产品或改进错误消息，而不是编写页面的查询。
• 应由该技术自身文档负责的参考资料查询。

助手改变了点击预测的价值：如今，页面即使没有被点击，也可能被引用。评估主题簇时，应看你的页面是否会成为答案的素材来源，而不是看预计流量；并以引用量和访问量，而非仅点击量，预测回报。

列表中最简单的内容会最先失去点击量。Stack Overflow 2025 年开发者调查（超过 49,000 名受访者）显示，84% 的受访者正在使用或计划使用 AI 工具，66% 的受访者将“AI 解决方案几乎正确，却又不完全正确”列为最让他们沮丧的问题；即使使用量上升，人们对这些答案的信任度仍在下降，从 2023 年的约 40% 降至 2025 年的 29%（因此，一行式答案会失去点击量，而验证、边缘情况和特定版本行为仍有价值）。JetBrains《2025 年开发者生态系统现状》调查（24,534 名受访者，调查于 2025 年 4 月至 6 月进行）显示，“在互联网上搜索开发相关信息”是开发者最常交由 AI 工具处理的第二项任务，仅次于编写样板代码——助手取代的是搜索步骤本身，而不只是搜索结果。

降低那些全部价值都在于一句话答案的主题簇的优先级，但仍将它们保留在地图中：助手依然会根据你发布的内容来组织答案。正如 Rand Fishkin 所言：“访问量减少，但影响力不变”（SparkToro，发布于 2026-08-14）。

调用示例

无论请求如何措辞，都应生成同一种产物：一份 Markdown 关键词地图。当请求范围小于完整地图时，删减章节，绝不要另造一种结构。

• “为我们的 Postgres 连接池文档整理一份关键词列表”——完整流程，涵盖两种采用模式，并先进行访谈。
• “这是我们的搜索控制台导出数据和过去 90 天的文档搜索日志，找出我们接下来应该写什么”——数据已提供，因此跳过数据来源问题，直接开始收集和聚类。
• “把上季度的支持工单转化为故障排查页面目标”——仅处理错误类型；对问题进行规范化、聚类、排序，并将每个主题簇对应到一个错误条目。
• “我们下个月要发布 Rust SDK，应该随它一起发布什么？”——仅沿一个维度扩展；地图应服务于已确定的发布计划，而非整个季度的产能。
• “我们应该更新现有的哪些页面，而不是编写新页面？”——仅进行筛查（步骤 2 加上排名接近的集合），输出仅限“优先修复”和“排名主题簇”章节。

输出

生成一份包含以下章节的 Markdown 报告：

# Keyword map: <product / scope>

## Scope
Axes, adoption mode(s), owned surfaces, sources available and unavailable.

## Ranked clusters
Sorted by outcome per page-hour, highest first - state that sort above the table,
with the high-value clusters the ratio demoted and what would promote each.
| Cluster | Primary query | Variants | Family | Evidence (source, count, date) | Incumbent | Target surface | Existing URL or "new" | Priority |

## Company-adoption set
Same table, kept separate so neither volume nor the efficiency ratio can bury it.

## Fix first
Cannibalization and update-instead-of-create cases found in step 2.

## Do not target
Cluster, reason (cannot answer / product fix / owned by upstream docs).

## Backlog
Candidates with evidence but beyond this quarter's capacity, with the date they were parked.

./references/keyword-map-example.md 中提供了一个完整示例，以及一个未达门槛的地图反例。

达标条件

满足以下六项即表示地图完成。不断迭代，直到全部满足，并明确说明结果。

1. 每个排名关键词都至少有一项证据，且包含来源、计数、日期和 Measured/User-provided/Estimated 标签。
2. 至少 70% 的排名集群，其首要证据来自第 1–4 层（第一方）。低于此比例，地图就只是伪装成研究的猜测——回到第 3 步。
3. 没有任何集群仅凭关键词工具的搜索量来排名。
4. 每个集群都恰好对应一个规范目标页面，且不同意图的两个集群不得指向同一页面。
5. “不针对”列表不得为空。拒绝项为零的研究轮次，说明没有应用可胜出性筛选。
6. 排名表说明了排序方式，列出被该比率降级的高价值集群及各自的晋升条件；公司采用场景集合有自己的已填写目标数量，不沿用该比率的排序。

70% 的底线是此技能自行设定的基线，并非已发布的基准。应如实报告；如果产品有丰富的第一方数据，就提高该比例；如果产品尚未发布且几乎没有第一方数据，就在“范围”部分明确说明并降低该比例。

后续衡量清单

跟踪覆盖率、排名变化和到达量：

• 覆盖率——有已上线目标页面的排名集群占比。
• 排名变化——进入前列搜索结果的临界排名查询词。
• 到达量——每个页面发布后，精确字符串对应的第一方查询词计数。

不要用已发布页面数量作为成果指标——它衡量的是写作团队，而非研究。

失败模式

• 矩阵爆炸。 将每种模板与每个修饰词交叉组合，会产生数千个没人会搜索的单元格。每个单元格都必须以证据为准入条件；没有门槛的矩阵会催生门页。
• 每张工单对应一个页面。 跳过错误归一化，会将一个原因扩增成十个彼此竞争的单薄页面。
• 版本腐化。 与某个版本绑定的关键词会悄然过时。为绑定版本的集群标注复查日期。
• 意图冲突。 相同的表述可能是在描述错误，也可能是在查找配置。分配目标页面前，先检查当前搜索结果实际回答了什么。
• 把博客当作垃圾场。 将文档类查询引导到博客，会把答案埋在产品中无人会链接到的地方。
• 遗漏销售团队会遇到的问题。 限制、权限、合规和迁移问题很少出现在公开渠道；应询问负责回答这些问题的人。

参考资料

• ./references/query-pattern-library.md - 查询类别、修饰词词汇表、扩展方法和错误字符串归一化。
• ./references/demand-evidence-sources.md - 各来源的提取指南、偏差，以及可选的工具集成说明。
• ./references/keyword-map-example.md - 一份完整的关键词地图示例，以及一个失败的反例。
• ./references/published-findings.md - 此技能引用的所有数据及其来源，以及自行设定的基线。

交接给以下技能，并与其互补：

• samber/developer-relations-skills@developer-troubleshooting-docs - 编写此地图所指向的错误条目。
• samber/developer-relations-skills@docs-seo - 在目标页面创建后处理页面内和技术 SEO。
• samber/developer-relations-skills@developer-docs-structure-audit - 独立于搜索需求，检查文档集的结构性缺口。
• samber/developer-relations-skills@devrel-content-calendar - 将由此产生的主题安排到一个季度中。
• samber/developer-relations-skills@developer-segmentation - 为采用模式划分所假设的受众细分命名。