shipping-and-launch

发布与上线

概览

带着把握去发布。目标不只是“部署成功”，而是要在有监控、有回滚预案、清楚知道成功标准的前提下安全发布。每一次上线都应该具备可回退、可观测和渐进推进三个特征。

何时使用

• 某个功能第一次发到生产环境
• 向用户发布重大改动
• 做数据或基础设施迁移
• 打开 beta 或 early access 计划
• 任何带风险的部署，实际上也就是所有部署

发布前检查清单

代码质量

• 所有测试通过，包括 unit、integration、e2e
• 构建成功且无警告
• Lint 与类型检查通过
• 代码已评审并批准
• 没有必须在发布前解决的 TODO 注释
• 生产代码里没有 console.log 调试语句
• 错误处理覆盖了预期失败模式

安全

• 代码与版本控制中没有 secrets
• npm audit 没有 critical 或 high 漏洞
• 所有对用户开放的 endpoint 都做了输入校验
• 已配置认证与授权检查
• 安全头已配置，例如 CSP、HSTS
• 认证相关接口具备限流
• CORS 只允许明确来源，而不是通配符

性能

• Core Web Vitals 处于 “Good” 区间
• 关键路径上没有 N+1 查询
• 图片已优化，包括压缩、自适应尺寸、懒加载
• Bundle 大小在预算内
• 数据库查询有合适索引
• 静态资源与高频查询已配置缓存

可访问性

• 所有交互元素都支持键盘导航
• 屏幕阅读器能正确传达页面内容与结构
• 颜色对比满足 WCAG 2.1 AA，例如正文 4.5:1
• Modal 和动态内容的焦点管理正确
• 错误信息足够清晰，并与表单字段关联
• axe-core 或 Lighthouse 中没有无障碍警告

基础设施

• 生产环境变量已设置
• 数据库迁移已应用，或已准备好应用
• DNS 与 SSL 已配置
• CDN 已为静态资源配置
• 日志和错误上报已配置
• 健康检查接口存在且响应正常

文档

• README 已更新任何新的启动要求
• API 文档是最新的
• 任何架构决策都已写 ADR
• Changelog 已更新
• 面向用户的文档已更新，如适用

Feature Flag 策略

通过 feature flag 发布，让部署与发布解耦：

// Feature flag check
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // New feature: task sharing
  return <TaskSharingPanel task={task} />;
}

// Default: existing behavior
return null;

Feature flag 生命周期：

1. DEPLOY with flag OFF     → Code is in production but inactive
2. ENABLE for team/beta     → Internal testing in production environment
3. GRADUAL ROLLOUT          → 5% → 25% → 50% → 100% of users
4. MONITOR at each stage    → Watch error rates, performance, user feedback
5. CLEAN UP                 → Remove flag and dead code path after full rollout

规则：

• 每个 feature flag 都有 owner 和过期时间
• 全量发布后 2 周内清理掉 flag
• 不要嵌套 feature flag，否则组合会指数增长
• 在 CI 中同时测试 flag 开和关两种状态

分阶段发布

发布顺序

1. DEPLOY to staging
   └── Full test suite in staging environment
   └── Manual smoke test of critical flows

2. DEPLOY to production (feature flag OFF)
   └── Verify deployment succeeded (health check)
   └── Check error monitoring (no new errors)

3. ENABLE for team (flag ON for internal users)
   └── Team uses the feature in production
   └── 24-hour monitoring window

4. CANARY rollout (flag ON for 5% of users)
   └── Monitor error rates, latency, user behavior
   └── Compare metrics: canary vs. baseline
   └── 24-48 hour monitoring window
   └── Advance only if all thresholds pass (see table below)

5. GRADUAL increase (25% -> 50% -> 100%)
   └── Same monitoring at each step
   └── Ability to roll back to previous percentage at any point

6. FULL rollout (flag ON for all users)
   └── Monitor for 1 week
   └── Clean up feature flag