Developer Onboarding

开发者入门

何时使用

当你需要通过精心设计的快速入门、教程和示例应用，让开发者快速完成 "Hello World" 时使用本技能。触发词：开发者入门、首次价值时间、快速入门指南、Hello World 教程、开发者激活、入门清单、示例应用、新手体验、降低...

让开发者从注册到跑通代码尽可能快，然后引导他们走向更深层的使用。

概述

开发者入门是介于"我刚注册"和"我知道怎么用了"之间的关键窗口。开发者给你的注意力大约只有 10 分钟。每一秒的困惑、每一条没有指引的错误信息、每一次"按理应该能用但就是不行"的时刻，都会让你失去用户。

优秀的入门体验像是和一位早已预判你每个问题的伙伴结对编程。糟糕的入门体验则像是被丢到一座陌生的城市，手里还没有地图。

开始之前

先复习 /devmarketing-skills/skills/developer-audience-context 技能，了解你的目标开发者。一个做 side project 的爱好者，与一个为生产环境评估工具的企业架构师，所需要的入门体验是不同的。再复习 /devmarketing-skills/skills/developer-signup-flow，确保注册流程能顺畅地衔接到入门环节。

首次价值时间优化

什么是"首次价值"

首次价值不是"成功调用了一次 API"。首次价值是开发者看到你的工具为他做了一件有用的事。

衡量首次价值时间（TTFV）

在每个阶段记录时间戳：

signup_completed: 2024-01-15T10:00:00Z
dashboard_loaded: 2024-01-15T10:00:05Z
api_key_copied: 2024-01-15T10:01:30Z
first_api_call: 2024-01-15T10:04:45Z
first_successful_response: 2024-01-15T10:04:46Z  # TTFV = 4:46

分类基准：

• 简单 API：< 5 分钟
• 需要安装的 SDK：< 10 分钟
• 复杂基础设施：< 30 分钟
• 自托管：< 60 分钟

清除 TTFV 障碍

梳理每一步并消除卡点：

常见的 TTFV 杀手：

1. 访问面板之前先要求邮箱验证
2. API key 藏在账号设置深处
3. 快速入门假设依赖已经装好
4. 第一个示例就需要付费功能
5. 错误信息没有给出解决办法
6. 文档搜索结果全是过时教程

TTFV 审计流程：

1. 新建一个账号（全新浏览器，不带任何 cookie）
2. 录屏记录你的前 30 分钟
3. 记下每一个让人困惑或别扭的瞬间
4. 给每个步骤计时
5. 换 5 种不同的开发者人设重复一次

快速入门清单设计

理想的快速入门结构

# 快速入门：5 分钟完成 [具体目标]

你将完成：[最终效果的截图或描述]

前置条件：
- Node.js 18+ (check: node --version)
- npm 或 yarn

## 步骤 1：安装 SDK
[一行命令，带复制按钮]

## 步骤 2：使用你的 API key 初始化
[带占位符的代码，带复制按钮]

## 步骤 3：发起你的第一个请求
[完整可运行的示例，带复制按钮]

## 步骤 4：查看结果
[展示预期输出]

## 下一步
- [常见第二个任务的链接]
- [完整文档的链接]

真正有效的清单模式

进度指示器（Stripe 风格）：

你的集成进度：
[x] 创建账号
[x] 获取 API key
[ ] 安装 SDK
[ ] 发起首次 API 调用
[ ] 处理 Webhook

情境化的下一步（Vercel 风格）：

你已经部署了你的第一个站点。

接下来做什么？
[ ] 添加自定义域名
[ ] 配置环境变量
[ ] 启用分析

快速入门的常见失败

前置上下文过多：

# 不好的写法：先讲鉴权的历史
在开始之前，我们先来理解一下 OAuth 2.0……
[500 字的背景铺垫]

# 好的写法：直接动手
安装 SDK 并发起你的第一个鉴权请求。

假设环境已就绪：

# 不好的写法
执行 `npm install` 来安装依赖。

# 好的写法
npm install our-sdk
# 或使用 yarn：yarn add our-sdk
# 或使用 pnpm：pnpm add our-sdk

隐藏的前置条件：

# 不好的写法（前置条件藏到第 3 步才出现）
步骤 3：连接 Redis
首先，确保 Redis 正在运行……

# 好的写法（前置条件一开始就列出）
前置条件：
- Redis 6+ 在本地运行 (docker run -p 6379:6379 redis)

交互式教程 vs 静态教程

何时使用交互式教程

交互式教程适用于：

• 复杂的安装序列
• 能从即时反馈中获益的概念
• 你能完全掌控环境的入门流程
• 需要 API key 或凭证的功能

交互式教程工具：

• 嵌入式代码编辑器（CodeSandbox、StackBlitz）
• 终端模拟器（Instruqt、Killercoda）
• 面板内引导（Appcues、Pendo）
• 交互式 Notebook（Jupyter、Observable）

何时静态文档更合适

静态文档更适合：

• 参考类文档
• 可复制的代码片段
• 涉及本地开发的步骤
• 内容频繁变动的部分

混合方式

最佳实践：两种都提供

# 发起你的第一个 API 请求

## 快速版（复制即用）
[带复制按钮的代码块]

## 交互版
[在 StackBlitz 中打开] [在 CodeSandbox 中尝试]

## 视频讲解
[5 分钟的嵌入视频]

交互式教程的 UX 准则

应该做：

• 自动保存进度
• 允许跳过
• 显示剩余预估时间
• 提供跳转到静态文档的出口
• 在手机浏览器中至少能正常浏览

不应该做：

• 教程强制要求注册账号
• 视频自动播放
• 把内容锁在"完成前置步骤"之后
• 静默地让空闲会话超时
• 指定特定 IDE 或浏览器

示例应用与模板

模板策略

分层策略：

1. 极简示例（Hello World）

   • 单文件
   • 除了你的 SDK 外零依赖
   • 30 秒跑通
   • 目的：证明 SDK 能用

2. 入门模板（基础应用）

   • 简单的目录结构
   • 展示常见模式
   • 5 分钟跑通
   • 目的：真实项目的起点

3. 生产级模板（完整应用）

   • 生产就绪的架构
   • 包含鉴权、错误处理和测试
   • 30 分钟跑通
   • 目的：参考实现

模板组织

github.com/your-org/
├── examples/
│   ├── minimal/
│   │   ├── node/
│   │   ├── python/
│   │   └── go/
│   ├── starter/
│   │   ├── nextjs/
│   │   ├── express/
│   │   └── fastapi/
│   └── production/
│       ├── saas-starter/
│       └── internal-tool/

模板维护

跑不通的模板，比没有模板更糟糕。

模板健康清单：

• CI 每周对所有模板跑一次
• 依赖每月更新
• SDK 版本固定并随发版更新
• README 每季度由新贡献者验证
• 移除前先添加弃用提示

真实案例

优秀模板：Supabase

• 覆盖多种框架的模板
• 一键部署到 Vercel / Netlify
• 包含鉴权、数据库和存储模式
• 持续维护

优秀模板：Clerk

• 框架专属的快速入门
• 配齐鉴权流程
• 渐进式复杂度（极简 → 全功能）

优雅地处理入门失败

常见失败点

1. 安装失败

   • 依赖冲突
   • 版本不匹配
   • 平台相关问题

2. 鉴权失败

   • API key 无效
   • Token 过期
   • 环境错误（测试 vs 生产）

3. 首次请求失败

   • 网络问题
   • CORS 问题
   • 限流
   • 请求格式不合法

错误信息设计

糟糕的错误信息：

Error: Request failed with status 401

好的错误信息：

鉴权失败：API key 无效

你的 API key 以 'sk_test_' 开头，但你正在调用生产端点。

修复方法：
1. 使用生产环境的 API key（以 'sk_live_' 开头），或者
2. 把端点改为 https://api.example.com/test/

文档：https://docs.example.com/auth#environments

主动预防失败

实时检测常见错误：

// 客户端 SDK 捕获常见错误
if (apiKey.startsWith('sk_test_') && endpoint.includes('/v1/')) {
  console.warn(
    'Warning: Using test API key with production endpoint. ' +
    'This will fail. Use production key or test endpoint.'
  );
}

恢复流程

面板内的错误恢复：

你的集成出现了问题。

我们检测到：
- 上次 API 调用：2 小时前
- 状态：401 Unauthorized
- 可能原因：API key 已轮换

[重新生成 API key] [查看错误日志] [联系支持]

衡量激活指标

什么是激活

激活 = 开发者获得了足够多的成功、愿意继续使用你的产品。

不同产品有不同的激活定义：

核心激活指标

激活率

已激活用户 / 注册用户 × 100

基准：自服务开发者产品为 20-40%

激活耗时

从注册到激活事件的中位时间

基准：API < 10 分钟，基础设施 < 1 小时

按群组看激活 按周或按月跟踪群组，识别改进效果：

第 1 周群组：激活率 25%
第 2 周群组：激活率 28%（改进了错误信息）
第 3 周群组：激活率 35%（新增了交互式教程）

先行指标

跟踪能够预测激活的行为：

后置指标

确认激活确实带来了价值：

激活漏斗示例

注册：1,000
├── 访问面板：950 (95%)
├── 浏览快速入门：700 (74%)
├── 复制 API key：500 (71%)
├── 发起首次 API 调用：350 (70%)
├── 收到成功响应：300 (86%)  ← 激活
├── 调用 10+ 次：150 (50%)
└── 第 7 日回访：100 (67%)

入门邮件序列

邮件时机

邮件内容原则

应该做：

• 包含代码片段（带语法高亮）
• 链接到具体的文档页面
• 允许直接回复求助
• 激活后立即停止序列

不应该做：

• 在入门期间发送营销内容
• 需要点击才能看到内容
• 一天之内发送超过一封邮件
• 激活之后还继续发邮件

真实开发者工具案例

优秀入门：Stripe

• 测试 API key 立即可见
• 面板内有"完成首笔扣款"的交互式引导
• 语言专属的代码示例
• 错误信息附带修复建议
• 进度指示器显示完成度

优秀入门：Railway

• 一键部署模板
• 常见框架无需任何配置
• 数秒即可获得预览 URL
• 清晰展示免费额度上限

优秀入门：Planetscale

• 交互式数据库浏览器
• 提供从现有数据库导入
• SQL 示例匹配你的 schema
• 用可视化方式讲解 branch 工作流

应避免的糟糕入门模式

• 多步骤向导且无法跳过
• "完善资料"卡住代码访问
• 必须搜索才能找到快速入门的文档
• 快速入门假设了太多前置设置
• 错误信息没有任何指引

工具

入门平台

• Appcues - 应用内引导和清单
• Pendo - 带入门功能的产品分析
• Userflow - 无代码入门流程
• CommandBar - 面向开发者的命令面板，自带入门能力

交互式文档

• CodeSandbox / StackBlitz - 浏览器内的代码环境
• Killercoda - 交互式终端场景
• ReadMe - 带"在线试用"的 API 文档
• Mintlify - 内嵌代码运行器的现代文档

邮件与生命周期

• Customer.io - 行为触发的邮件
• Loops - 面向 SaaS 的邮件
• Intercom - 即时通讯 + 邮件入门

分析

• Amplitude - 入门漏斗分析
• PostHog - 开源替代品
• Heap - 自动捕获，支持回溯分析

相关技能

• /devmarketing-skills/skills/developer-signup-flow - 抵达入门起点
• /devmarketing-skills/skills/developer-audience-context - 你在为谁做入门
• /devmarketing-skills/skills/free-tier-strategy - 他们在不付费的情况下能做什么

局限

• 仅当任务与上游来源及本地项目上下文明确匹配时使用本技能。
• 在应用变更前，请验证命令、生成的代码、依赖、凭证以及外部服务行为。
• 不要把示例当作特定环境测试、安全审查或针对破坏性/高成本操作的用户审批的替代品。