Skip to content

fix(seo): SEO 优化:修复 canonical 冲突、添加结构化数据、补充多语言 description、优化 sitemap 和更新时间#100

Open
live-alife wants to merge 31 commits into
QwenLM:mainfrom
live-alife:seo
Open

fix(seo): SEO 优化:修复 canonical 冲突、添加结构化数据、补充多语言 description、优化 sitemap 和更新时间#100
live-alife wants to merge 31 commits into
QwenLM:mainfrom
live-alife:seo

Conversation

@live-alife

@live-alife live-alife commented May 27, 2026

Copy link
Copy Markdown
Contributor

概述

对文档站进行系统性的 SEO 优化,涵盖元数据修复、结构化数据、多语言 description、sitemap 优化和无障碍改进,共修改 333 个文件。

主要改动

Canonical 和 hreflang

 - 为每个文档页动态生成独立的 canonical URL(之前所有页面都指向 /)
 - 动态生成 hreflang 标签,指向各语言版本(之前都指向语言首页)
 - 添加 x-default hreflang 指向英文版本
 - 修复根路径 canonical 冲突:删除全局 layout 的 alternates,根跳转页改用 Next.js metadata 导出声明 canonical 指向 qwen.ai/qwencode
image image image

页面 Description

 - 为 89+ 个文档页添加专属 description frontmatter,覆盖 users/、features/、developers/、design/、plans/ 目录
 - 为缺少 frontmatter description 的页面自动从正文提取摘要作为兜底(跳过代码块、标题等,取首个有意义的段落,截断到 160 字符)
 - 补充 de、fr、ja、pt-BR、ru、zh 六种语言的核心页、功能页、开发者页专属 SEO description
 - 移除未使用的 keywords meta 标签(已被主流搜索引擎弃用)
image image image image

OG 图片

 - 创建目录专属的 OG 图片:Qwen Code Docs(默认)、Qwen Code Blog、Qwen Code Showcase
 - 添加品牌 fallback 图片,用于未映射目录
 - 从 SVG 替换为 PNG 格式
 - 更新 generateMetadata 根据页面路径自动选择 OG 图片
image image image

Sitemap 优化

 - 使用 git log 最后提交时间作为 lastModified,而非构建时间,提供更准确的更新频率信号
 - 移除根路径跳转页,仅保留实际文档内容页
 - 支持 MDX 文件
 - 优化性能:使用批量 git log --name-only 一次获取所有文件时间,避免 865 次子进程调用

结构化数据(JSON-LD)

 - 全局添加 WebSite 和 Organization 结构化数据,帮助搜索引擎理解站点身份
 - 所有文档页添加 BreadcrumbList 面包屑结构化数据,支持搜索结果中的面包屑路径展示
 - 博客文章自动添加 BlogPosting 结构化数据,包含标题、描述、发布时间、作者等信息
image

无障碍和语义化

 - 为 5 个视频组件添加 aria-label,使用已有标题数据自动生成(Hero 视频、弹窗播放器、showcase 详情页、IDE 集成演示)
 - 移除微信通道博客文章(7 种语言)的重复 h1 标题,保留 BlogPostHeader 组件渲染的 h1
 - 修复 overview 页面视频标签语义错误
 - 增加各语言 blog 页面缺失的 H1 标题
image image

静态导出适配

 - 适配 GitHub Pages 静态导出环境
 - favicon、manifest 等静态资源路径使用 withBasePath() 处理
 - sitemap 和文档页路由添加 generateStaticParams 支持静态生成
 - 删除不兼容静态导出的 middleware.ts
 - 优化开发环境资源加载(仅在开发模式下加载 index.css)

CI/CD 优化

 - 设置 fetch-depth: 0 拉取完整 git 历史,修复 GitHub Actions 浅克隆导致所有页面"最后更新时间"都显示为 push 当天的问题
 - 使 Nextra 能获取每个文件真实的 git 最后提交时间
image

其他修复

 - 清理翻译工具(aone-copilot)污染:删除 6 种语言 weekly-update-2026-05-21.mdx 末尾泄漏的 shell 输出
 - 补全俄语 developers/tools/introduction.md 翻译(62 行新增)
 - 优化博客索引页标题和语言首页跳转
 - 优化 showcase 详情页标题
image image

修改的文件

 - .github/workflows/deploy-docs.yml — CI 配置优化
 - website/app/layout.tsx — 移除全局 alternates 和 keywords
 - website/app/page.tsx — 根路径 canonical 标签
 - website/app/sitemap.ts — 基于 git 的 lastModified 和性能优化
 - website/app/[lang]/[[...mdxPath]]/page.jsx — canonical、hreflang、OG 图片逻辑、兜底 description
 - website/src/lib/structured-data.ts — 结构化数据生成
 - website/src/components/ — 视频 aria-label、博客索引页优化
 - website/public/assets/ — 4 张 OG 图片(PNG)
 - website/content/ — 89+ 个内容文件添加 description frontmatter
 - 333 个文件总计,+1841/-209 行

测试

 - ✅ 构建成功(npm run build)
 - ✅ 开发服务器正常(npm run dev)
 - ✅ Canonical 和 hreflang 标签正确生成
 - ✅ Sitemap 包含正确的 lastModified 时间
 - ✅ 结构化数据 JSON-LD 正确输出
 - ✅ OG 图片正确显示

影响范围

 - SEO:显著提升搜索引擎可见性和排名潜力
 - 无障碍:改善屏幕阅读器用户体验
 - 性能:Sitemap 生成性能优化
 - 多语言:6 种非英语语言的 description 覆盖更完整

live-alife added 30 commits May 27, 2026 14:11
- 修复 canonical URL,从固定指向根目录改为指向当前页面
- 动态生成 hreflang 标签,指向当前页面的各语言版本
- 新增 x-default hreflang,无匹配语言时默认展示英文版本
- 删除 KEYWORDS 常量定义
- 从 metadata 中移除 keywords 字段
- 主流搜索引擎已不再使用 keywords 标签
- quickstart: 5 分钟入门指南
- common-workflow: 常见工作流概览
- integration-vscode: VS Code 扩展介绍
- integration-zed: Zed 编辑器集成
- integration-jetbrains: JetBrains IDE 集成
- integration-github-action: GitHub Actions 自动化
- 每个 description 包含品牌词 Qwen Code + 页面主旨
- 加入行动号召词、长尾关键词提升搜索点击率
- 控制长度在 150-160 字符以内
- 涵盖: approval-mode, arena, channels, checkpointing, code-review,
  commands, dual-output, followup-suggestions, headless, hooks,
  language, lsp, mcp, memory, sandbox, scheduled-tasks, skills,
  status-line, sub-agents, tips, token-caching, tool-use-summaries
- configuration/: auth, model-providers, qwen-ignore, settings, themes, trusted-folders
- extension/: introduction, getting-started-extensions, extension-releasing
- reference/: keyboard-shortcuts
- support/: tos-privacy, troubleshooting, Uninstall
- 每个 description 包含品牌词 + 页面主旨 + 行动号召词
- design/ 目录 16 个文件:涵盖内存系统、频道设计、紧凑模式、子代理、命令重构等技术设计文档
- developers/ 目录 27 个文件:涵盖架构概览、贡献指南、SDK 文档、工具参考等开发者文档
- plans/ 目录 1 个文件:Agent Tool Display 实现计划
- 所有 description 包含品牌词 Qwen Code、页面主旨、行动号召词和长尾关键词
- 跳过隐藏的 examples/ 目录(sidebar 中设为 hidden)
- 将 markdown 图片语法 ![] 改为 HTML <video> 标签
- 添加 controls 属性允许用户控制播放
- 添加 width 属性控制视频宽度
- 添加浏览器不支持时的降级文本
- 解决了 alt 文本为空的 SEO 问题
- 添加 aria-label 无障碍描述属性
- 添加 margin-top 样式解决与代码块间距过近问题
- 移除浏览器不支持的降级文本(2026年已无必要)
- 新增 og-blog.svg、og-showcase.svg 专属图片
- 新增 og-fallback-brand.png 作为其他目录的兜底图片
- 更新 page.jsx 的 OG 图片映射逻辑,支持按目录自动选择
- 新增 getGitLastModified() 函数获取文件最后 git commit 时间
- 每个文档页面的 lastModified 现在反映真实修改时间
- 帮助搜索引擎更准确判断页面更新频率
- 在跳转页面添加 <link rel="canonical"> 标签
- 明确告诉搜索引擎 qwen.ai/qwencode 是真正的首页
- 帮助权重传递,改善 SEO 友好度
- 移除全局默认 canonical,避免首页生成重复规范链接
- 使用页面级 metadata 声明 qwen.ai/qwencode 为首页 canonical
- sitemap 支持 .mdx 内容,补齐博客和 showcase 收录入口
- 移除根路径跳转页,减少搜索引擎抓取噪音
- 新增 withBasePath 工具,统一生成带部署子路径的资源地址
- 修复 favicon 和 manifest 在 /qwen-code-docs 子路径下的引用
- 更新导航 logo 资源路径,避免生产环境请求到域名根目录
- 保持本地开发环境继续使用根路径资源
- 在页面缺少 frontmatter description 时从正文提取摘要
- 跳过 frontmatter、代码块、导入语句、图片和组件内容
- 同步补齐 openGraph 和 twitter 的描述信息
- 将重复使用全站默认描述的页面数量从 591 降至 24
- 为第一批核心入口页补充手写 SEO description
- 保留已有英文页面描述,不覆盖既有优化内容
- 确保新增描述包含 Qwen Code 品牌词和页面主旨
- 覆盖文档首页、IDE 集成、展示页和中文高意图功能页
- 为德法俄日葡 5 种语言的核心入口页补充手写 SEO description
- 覆盖首页、快速开始、认证、设置、MCP、Skills、命令、IDE、博客和展示页
- 确保新增描述包含 Qwen Code 品牌词,并匹配各页面主旨与搜索意图
- 为中德法俄日葡 6 种语言的功能关键词页补充手写 SEO description
- 覆盖 Hooks、Sandbox、Headless、Code Review、Checkpointing、Sub Agents、定时任务、模型提供方和主题页
- 保留英文已有描述不变,确保新增描述包含 Qwen Code 品牌词并匹配长尾搜索意图
- 为中德法俄日葡 6 种语言的开发者与扩展核心页补充 SEO description
- 覆盖架构、贡献指南、Python SDK、TypeScript SDK、MCP Server 和 Extensions 入门页
- 保留英文已有描述不变,确保新增描述包含 Qwen Code 品牌词并面向贡献者搜索意图
- 为各语言 blog 和 showcase 索引页补充包含 Qwen Code 的清晰标题
- 优化英文博客页 description,增强产品更新、AI coding 和开发者指南关键词
- 移除语言布局调试日志,减少本地开发和 CI 构建输出噪音
- 为全站注入 Organization 和 WebSite JSON-LD,增强品牌与站点实体识别
- 为文档页生成 BreadcrumbList,帮助搜索引擎理解多语言页面层级
- 为博客详情页添加 BlogPosting,补充标题、描述、日期、作者和发布者信息
- 为 sitemap metadata route 补充静态参数,修复 output export 下的访问错误

- 删除静态导出不支持的 middleware,避免本地和 CI 日志持续告警

- 已通过 npm run build 验证静态页面、robots 和 sitemap 可正常生成
为 4 个组件文件中的 5 个 <video> 标签添加 aria-label,
使用已有的 title 数据自动生成,覆盖 Hero 视频、弹窗播放器、
showcase 详情页和 IDE 集成演示。
- 为 sandbox 多语言文档补充本地化 description,并提升标题层级补齐 H1

- 修复英文 overview 的 description 被徽章链接误抓取的问题

- 新增 favicon.ico,并在开发环境禁用 Pagefind 加载以避免静态资源 500
- 为博客索引组件增加多语言 H1 和页面描述

- 仅在博客索引页隐藏 Nextra 面包屑,保留具体文章页导航

- 将各语言根路径定向到对应的 users/overview 页面,并同步 canonical 与 hreflang
- 删除 6 种语言 weekly-update-2026-05-21.mdx 末尾泄漏的 shell 输出
- 补全 ru/developers/tools/introduction.md 俄语翻译
- 将 OG 默认图片、博客图片、showcase 图片从 SVG 替换为 PNG
- 更新 page.jsx 中 OG_IMAGE_MAP 和 DEFAULT_OG_IMAGE 的文件扩展名
- 结构化数据中 WebSite.url 由写死的完整域名改为使用 siteUrl 参数动态拼接,避免部署域名变化时产生不一致
- 文档页 hreflang 只输出真实存在且非空的语言版本,语言首页 canonical 指向 overview

- sitemap 按 Git 记录生成每个内容文件的 lastModified,避免全部回退为构建当天

- 博客索引列表标题层级从 h3 调整为 h2,并同步 translator 模板 canonical/hreflang
GitHub Actions 默认浅克隆(fetch-depth: 1),导致构建时所有文件的
最后修改时间都变成 push 当天。设置 fetch-depth: 0 拉取完整历史,
使 Nextra 能获取每个文件真实的 git 最后提交时间。
channels-weixin-launch-announcement.mdx 同时使用了 BlogPostHeader
组件(h1)和 Markdown # 标题(h1),导致页面出现两个 h1。
删除 Markdown 中的 # 标题,保留组件渲染的 h1。覆盖 7 种语言。
- 为 39 个偏短 description 页面补充品牌词 Qwen Code 和页面主旨

- 将 description 控制在 150-160 字符,覆盖场景、痛点和点击意图

- 仅修改 frontmatter description,不调整正文内容
@live-alife live-alife changed the title fix(seo): 文档网站全面 SEO 优化 fix(seo): SEO 优化:修复 canonical 冲突、添加结构化数据、补充多语言 description、优化 sitemap 和更新时间 May 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant