为文档网站设计根路由重定向策略，将首页直接指向快速开始教程，…

# 开源SDK文档站多语言根路由重定向方案

一、目标梳理

• 访问根路径 / → 按用户语言自动跳转到对应语言的快速开始页
• 兼容三语言：/docs/zh、/docs/en、/docs/ja
• 旧链接（如 /v1/getting-started）需 301 永久重定向到新路径，避免 SEO 权重丢失

二、语言检测与跳转策略

优先级顺序：

1. Cookie 记忆：用户上次手动切换的语言（如 doc_lang=zh），优先级最高

2. URL 参数：支持 ?lang=ja 强制指定，便于分享链接

3. Accept-Language 请求头：服务端/边缘解析浏览器语言偏好

• zh* → /docs/zh/getting-started
• ja* → /docs/ja/getting-started
• 其他默认 → /docs/en/getting-started

4. 兜底默认英文，并在页面提供显式语言切换入口，切换后写入 Cookie

三、具体实现方案（按部署方式选一）

方案A：边缘/CDN 层（推荐，Cloudflare Workers / Vercel Edge）

```

请求 / 时：

1. 读 Cookie doc_lang → 命中则 302 到 /docs/{lang}/getting-started

2. 未命中则解析 Accept-Language → 匹配 zh/ja/en

3. 无匹配头 → 302 到 /docs/en/getting-started

```

方案B：Nginx 配置

```nginx

location = / {

# 根据语言映射变量 $lang（用 map 指令解析 Accept-Language）

return 302 /docs/$lang/getting-started;

}

location /v1/getting-started {

return 301 /docs/en/getting-started; # 或按语言分流

}

```

方案C：静态托管（GitHub Pages 等）

• 根路径放一个跳转页，用一段 JS 读取 navigator.language 后 location.replace() 跳转
• 缺点：无 SSR 检测，体验略差；建议配合 meta refresh 兜底

四、旧链接迁移（/v1/getting-started）

• 使用 301 永久重定向（保留 SEO 权重），映射到 /docs/en/getting-started（默认）或按 Accept-Language 分流
• 建议整理一份旧→新路径映射表，批量配置，覆盖 /v1/* 全部历史页面
• 上线后在 Google Search Console / Bing Webmaster 提交更新

五、注意事项

• 内部跳转用 302（语言可能变化），旧链接迁移用 301
• 设置 Vary: Accept-Language 响应头，避免 CDN 缓存串语言
• Sitemap 中为三种语言分别列出完整 URL，并配置 hreflang 标签
• 跳转逻辑上线前用 curl 模拟不同 Accept-Language 头做回归测试