Gatsby SEO 组件实战基于 Gatsby Head API 为页面注入元数据与富摘要【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文是 Gatsby 项目React-based framework with performance, scalability, and security built in中关于搜索引擎优化的官方实战指南通过 Gatsby Head API 构建一个可复用的SEO /组件为每个页面写入 title、description、Twitter 卡片等元数据并借助siteMetadata与useStaticQuery实现站点级默认值与页面级覆盖。读完本文你将掌握从gatsby-config配置、自定义 Hook 到组件封装、页面接入与 JSON-LD 结构化数据的完整链路可直接复制到自己的 Gatsby 站点使用。为什么需要 SEO 组件向页面添加元数据如 title 或 description是帮助 Google 等搜索引擎理解内容、决定何时将内容呈现在搜索结果中的关键。同时这些信息也会在你分享网站例如在 Twitter 上时被展示出来。使用 Gatsby Head API你可以修改页面的 document head。Gatsby 会自动提供对元数据服务端渲染的开箱即用支持并把它们加入 Gatsby 生成的静态 HTML 页面中从而帮助你的站点在搜索引擎中获得更好的排名与表现。阅读完本指南后你将拥有一个可在页面中直接使用的SEO /组件用于统一定义页面元数据。前置条件一个已初始化的 Gatsby 项目版本为gatsby4.19.0或更高Gatsby Head API 自 4.19.0 起内置支持。如果还没有项目可参考 Quick Start 快速开始 创建。Directions三步构建 SEO 组件第一步在gatsby-config中添加siteMetadatagatsby-config文件中的siteMetadata区块会被暴露到 GraphQL 数据层中被认为是存放站点元数据的最佳实践位置。siteUrl应填写部署目标的 URL例如生产域名这样后续的 meta 标签才能指向绝对 URL。在配置中添加以下键值module.exports { siteMetadata: { title: Using Gatsby Head, description: Example project for the Gatsby Head API, twitterUsername: gatsbyjs, image: /gatsby-icon.png, siteUrl: https://www.yourdomain.tld, }, }你随时可以扩展siteMetadata对象并随后按需定制SEO /组件。当像上面这样定义image时请确保在 static 文件夹 中存在同文件名、同扩展名的图片。官方示例仓库 examples/using-gatsby-head 中使用了完全一致的配置examples/using-gatsby-head/gatsby-config.ts中定义了同样的五个键值并额外设置了trailingSlash: never。该示例同时提供了.jsx与 TypeScript.tsx/.ts两种形态的实现TS 用户可直接参考 examples/using-gatsby-head/src/components/seo.tsx 与 examples/using-gatsby-head/src/hooks/use-site-metadata.tsx。第二步创建useSiteMetadata自定义 Hook由于SEO /组件需要使用刚放入siteMetadata的信息你可以创建一个名为useSiteMetadata的自定义 React Hook 来获取这些信息这样也能在其他地方复用这些值。在src/hooks下创建新文件use-site-metadata.jsx通过 useStaticQuery Hook 从site接口查询信息import { graphql, useStaticQuery } from gatsby export const useSiteMetadata () { const data useStaticQuery(graphql query { site { siteMetadata { title description twitterUsername image siteUrl } } } ) return data.site.siteMetadata }此后你可以直接从该 Hook 中获取title、description等值。TypeScript 提示官方示例 examples/using-gatsby-head/src/hooks/use-site-metadata.tsx 通过定义ReturnValue类型并使用泛型useStaticQueryReturnValue对查询结果进行类型约束返回值data.site.siteMetadata便拥有了完整的类型推断。第三步编写 SEO 组件在src/components下创建新文件seo.jsx。你的 SEO 组件会接收title、description、children等 props当未传入 props 时useSiteMetadataHook 获取的信息会作为 fallback 兜底。对于不会随页面变化的项例如 Twitter 用户名直接使用useSiteMetadata的数据。完整的 SEO 组件如下import React from react import { useSiteMetadata } from ../hooks/use-site-metadata export const SEO ({ title, description, pathname, children }) { const { title: defaultTitle, description: defaultDescription, image, siteUrl, twitterUsername } useSiteMetadata() const seo { title: title || defaultTitle, description: description || defaultDescription, image: ${siteUrl}${image}, url: ${siteUrl}${pathname || }, twitterUsername, } return ( title{seo.title}/title meta namedescription content{seo.description} / meta nameimage content{seo.image} / meta nametwitter:card contentsummary_large_image / meta nametwitter:title content{seo.title} / meta nametwitter:url content{seo.url} / meta nametwitter:description content{seo.description} / meta nametwitter:image content{seo.image} / meta nametwitter:creator content{seo.twitterUsername} / link relicon hrefdata:image/svgxml,svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 100 100text y0.9em font-size90/text/svg / {children} / ) }所有 props 都是可选的因为每个值都有默认值或 fallback。pathnameprop 是页面的相对路径因此需要用siteUrl拼接出绝对 URL。你可以用其他键扩展seo对象但建议遵循prop || fallback的模式确保任何值都不会是undefined。实现细节seo对象中title、description等值实际上构成了页面级的解析后元数据而pathname之所以要拼接siteUrl是因为Head函数只能拿到location.pathname这类相对信息——Gatsby Head API 提供给Head的 props 中不包含绝对地址详见下文Head 函数接收的属性。在页面中使用 SEO 组件当只想使用 SEO 组件的默认值时例如首页可以不传任何 props 直接导入渲染import React from react import { SEO } from ../components/seo const IndexPage () { return ( main Hello World /main ) } export default IndexPage // highlight-start export const Head () ( SEO / ) // highlight-end要覆盖个别值则通过 SEO 组件已定义的 props 传入import React from react import { SEO } from ../components/seo const SecondPage () { return ( main Hello World /main ) } export default SecondPage // highlight-start export const Head () ( SEO titlePage Two / ) // highlight-end要为页面添加一次性one-off的 meta 标签请向 SEO 组件提供childrenimport React from react import { SEO } from ../components/seo const OneOffPage () { return ( main Hello World /main ) } export default OneOffPage // highlight-start export const Head () ( SEO titleOne Off Page script typeapplication/ldjson{JSON.stringify({})}/script /SEO ) // highlight-end动态页面示例在官方示例 examples/using-gatsby-head/src/pages/parks/{Park.name}.tsx 中模板页通过HeadFCQueryReturn类型接收data与location将 GraphQL 查询出的park.name、park.description作为 props 传给 SEO并把location.pathname传给pathname——这是数据驱动元数据的典型用法export const Head: HeadFCQueryReturn ({ data: { park }, location }) ( SEO title{park.name} description{park.description} pathname{location.pathname} {/* 页面级 children 元数据 */} /SEO )Additional Information深入 Gatsby Head API数据块script与动态脚本数据块script标签如script typeapplication/ldjson可以放进Head函数但动态脚本更适合在页面或组件中使用 Gatsby Script Component 加载。如果需要编辑html或body请阅读 Gatsby Head 参考指南——gatsby5.5.0起支持在Head中通过html langen /、body classNamemy-body-class /设置标签属性Gatsby 会将这些属性注入最终 HTML且Head中定义的html/body会覆盖onRenderBody中setHtmlAttributes与setBodyAttributes设置的属性。标签去重Deduplication为避免head中出现重复标签可以在标签上使用id属性确保只渲染一个。看下面的例子const SEO ({ children }) ( titleHello World/title link idicon relicon hrefglobal-icon / {children} / ) export const Head () ( SEO link idicon relicon hreficon-specific-for-this-page / /SEO )这种情况下只会渲染第二个link idicon relicon hreficon-specific-for-this-page /。在一组拥有相同id的标签中最后一个生效并被写入 HTML。官方示例中的 favicon 图标即利用了这一机制首页提供默认图标{Park.name}.tsx模板页则通过 children 传入带相同idfavicon-icon的页面专属图标实现覆盖。Head 函数接收的属性Head函数会接收以下 propsGatsby Head 参考指南location.pathnameLocation 对象的 URL 路径params页面带有matchPath使用 client-only routes时的 URL 参数data通过导出的 GraphQL query 传入页面的数据pageContext创建页面时传入的上下文对象export const Head ({ location, params, data, pageContext }) ( title{pageContext.title}/title meta namedescription content{data.page.description} / meta nametwitter:url content{https://www.foobar.tld/${location.pathname}} / / )使用 Gatsby Head 的注意事项参考 Gatsby Head API 文档使用时有以下几点需要留意Head导出只能定义在页面内包括通过createPage创建的模板中不能定义在普通组件里页面卸载时 Gatsby Head 的内容会被清空因此每个页面都需要在自身的head中定义它需要的内容Head函数必须返回合法的 JSXHead函数内合法的标签为link、meta、style、title、base、script和noscriptgatsby5.6.0起Head可以访问你在wrapRootElementAPI 中定义的 React Context但wrapRootElement应只用于搭建 Context 提供者UI 组件应定义在wrapPageElementAPI 中。Rich Snippets富摘要 / 结构化数据Google 会使用网页中发现的结构化数据来理解页面内容并收集关于网页乃至整个互联网世界的信息。例如下面这段采用 JSON-LD 格式Linked Data 的 JavaScript 对象表示法的结构化数据片段可能出现在一家名为 Spooky Technologies 公司的联系页面上描述其联系信息script typeapplication/ldjson { { context: https://schema.org, type: Organization, url: https://www.spookytech.com, name: Spooky technologies, contactPoint: { type: ContactPoint, telephone: 5-601-785-8543, contactType: Customer Support } } } /script本地开发期间你可以使用 Google 的 Rich Results Test 检查是否传入了有效信息部署后Google Search Console 的富结果状态报告Rich result status reports则有助于监控页面健康状态并排查模板或服务方面的问题。进阶TypeScript 用法如果项目使用 TypeScript官方示例 examples/using-gatsby-head 提供了完整参考。与 JS 版本相比主要有三处差异配置文件gatsby-config.ts中通过import type { GatsbyConfig } from gatsby声明类型Hook 类型use-site-metadata.tsx中为useStaticQuery传入ReturnValue泛型组件类型seo.tsx中通过React.FCReact.PropsWithChildrenSEOProps描述 props页面中则用HeadFCQueryReturn类型约束Head函数。更完整的说明参见 Using Gatsby Head with TypeScript。验证与排查本地验证开发模式下访问各页面查看浏览器开发者工具中的head区域确认 title、meta description、Twitter 卡片标签是否按预期渲染同时可用 Google Rich Results Test 检查结构化数据性能审计使用 Lighthouse 审计 检查 SEO 得分部署后监控借助 Google Search Console 的富结果状态报告持续监控页面健康度。附加资源Using Gatsby Head with TypeScriptGatsby Head 参考指南Gatsby Script Component使用 Lighthouse 审计官方示例仓库examples/using-gatsby-head包含seo.tsx、use-site-metadata.tsx、{Park.name}.tsx模板页等完整实现是本文所有代码的可运行版本【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Gatsby SEO 组件实战基于 Gatsby Head API 为页面注入元数据与富摘要【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文是 Gatsby 项目React-based framework with performance, scalability, and security built in中关于搜索引擎优化的官方实战指南通过 Gatsby Head API 构建一个可复用的SEO /组件为每个页面写入 title、description、Twitter 卡片等元数据并借助siteMetadata与useStaticQuery实现站点级默认值与页面级覆盖。读完本文你将掌握从gatsby-config配置、自定义 Hook 到组件封装、页面接入与 JSON-LD 结构化数据的完整链路可直接复制到自己的 Gatsby 站点使用。为什么需要 SEO 组件向页面添加元数据如 title 或 description是帮助 Google 等搜索引擎理解内容、决定何时将内容呈现在搜索结果中的关键。同时这些信息也会在你分享网站例如在 Twitter 上时被展示出来。使用 Gatsby Head API你可以修改页面的 document head。Gatsby 会自动提供对元数据服务端渲染的开箱即用支持并把它们加入 Gatsby 生成的静态 HTML 页面中从而帮助你的站点在搜索引擎中获得更好的排名与表现。阅读完本指南后你将拥有一个可在页面中直接使用的SEO /组件用于统一定义页面元数据。前置条件一个已初始化的 Gatsby 项目版本为gatsby4.19.0或更高Gatsby Head API 自 4.19.0 起内置支持。如果还没有项目可参考 Quick Start 快速开始 创建。Directions三步构建 SEO 组件第一步在gatsby-config中添加siteMetadatagatsby-config文件中的siteMetadata区块会被暴露到 GraphQL 数据层中被认为是存放站点元数据的最佳实践位置。siteUrl应填写部署目标的 URL例如生产域名这样后续的 meta 标签才能指向绝对 URL。在配置中添加以下键值module.exports { siteMetadata: { title: Using Gatsby Head, description: Example project for the Gatsby Head API, twitterUsername: gatsbyjs, image: /gatsby-icon.png, siteUrl: https://www.yourdomain.tld, }, }你随时可以扩展siteMetadata对象并随后按需定制SEO /组件。当像上面这样定义image时请确保在 static 文件夹 中存在同文件名、同扩展名的图片。官方示例仓库 examples/using-gatsby-head 中使用了完全一致的配置examples/using-gatsby-head/gatsby-config.ts中定义了同样的五个键值并额外设置了trailingSlash: never。该示例同时提供了.jsx与 TypeScript.tsx/.ts两种形态的实现TS 用户可直接参考 examples/using-gatsby-head/src/components/seo.tsx 与 examples/using-gatsby-head/src/hooks/use-site-metadata.tsx。第二步创建useSiteMetadata自定义 Hook由于SEO /组件需要使用刚放入siteMetadata的信息你可以创建一个名为useSiteMetadata的自定义 React Hook 来获取这些信息这样也能在其他地方复用这些值。在src/hooks下创建新文件use-site-metadata.jsx通过 useStaticQuery Hook 从site接口查询信息import { graphql, useStaticQuery } from gatsby export const useSiteMetadata () { const data useStaticQuery(graphql query { site { siteMetadata { title description twitterUsername image siteUrl } } } ) return data.site.siteMetadata }此后你可以直接从该 Hook 中获取title、description等值。TypeScript 提示官方示例 examples/using-gatsby-head/src/hooks/use-site-metadata.tsx 通过定义ReturnValue类型并使用泛型useStaticQueryReturnValue对查询结果进行类型约束返回值data.site.siteMetadata便拥有了完整的类型推断。第三步编写 SEO 组件在src/components下创建新文件seo.jsx。你的 SEO 组件会接收title、description、children等 props当未传入 props 时useSiteMetadataHook 获取的信息会作为 fallback 兜底。对于不会随页面变化的项例如 Twitter 用户名直接使用useSiteMetadata的数据。完整的 SEO 组件如下import React from react import { useSiteMetadata } from ../hooks/use-site-metadata export const SEO ({ title, description, pathname, children }) { const { title: defaultTitle, description: defaultDescription, image, siteUrl, twitterUsername } useSiteMetadata() const seo { title: title || defaultTitle, description: description || defaultDescription, image: ${siteUrl}${image}, url: ${siteUrl}${pathname || }, twitterUsername, } return ( title{seo.title}/title meta namedescription content{seo.description} / meta nameimage content{seo.image} / meta nametwitter:card contentsummary_large_image / meta nametwitter:title content{seo.title} / meta nametwitter:url content{seo.url} / meta nametwitter:description content{seo.description} / meta nametwitter:image content{seo.image} / meta nametwitter:creator content{seo.twitterUsername} / link relicon hrefdata:image/svgxml,svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 100 100text y0.9em font-size90/text/svg / {children} / ) }所有 props 都是可选的因为每个值都有默认值或 fallback。pathnameprop 是页面的相对路径因此需要用siteUrl拼接出绝对 URL。你可以用其他键扩展seo对象但建议遵循prop || fallback的模式确保任何值都不会是undefined。实现细节seo对象中title、description等值实际上构成了页面级的解析后元数据而pathname之所以要拼接siteUrl是因为Head函数只能拿到location.pathname这类相对信息——Gatsby Head API 提供给Head的 props 中不包含绝对地址详见下文Head 函数接收的属性。在页面中使用 SEO 组件当只想使用 SEO 组件的默认值时例如首页可以不传任何 props 直接导入渲染import React from react import { SEO } from ../components/seo const IndexPage () { return ( main Hello World /main ) } export default IndexPage // highlight-start export const Head () ( SEO / ) // highlight-end要覆盖个别值则通过 SEO 组件已定义的 props 传入import React from react import { SEO } from ../components/seo const SecondPage () { return ( main Hello World /main ) } export default SecondPage // highlight-start export const Head () ( SEO titlePage Two / ) // highlight-end要为页面添加一次性one-off的 meta 标签请向 SEO 组件提供childrenimport React from react import { SEO } from ../components/seo const OneOffPage () { return ( main Hello World /main ) } export default OneOffPage // highlight-start export const Head () ( SEO titleOne Off Page script typeapplication/ldjson{JSON.stringify({})}/script /SEO ) // highlight-end动态页面示例在官方示例 examples/using-gatsby-head/src/pages/parks/{Park.name}.tsx 中模板页通过HeadFCQueryReturn类型接收data与location将 GraphQL 查询出的park.name、park.description作为 props 传给 SEO并把location.pathname传给pathname——这是数据驱动元数据的典型用法export const Head: HeadFCQueryReturn ({ data: { park }, location }) ( SEO title{park.name} description{park.description} pathname{location.pathname} {/* 页面级 children 元数据 */} /SEO )Additional Information深入 Gatsby Head API数据块script与动态脚本数据块script标签如script typeapplication/ldjson可以放进Head函数但动态脚本更适合在页面或组件中使用 Gatsby Script Component 加载。如果需要编辑html或body请阅读 Gatsby Head 参考指南——gatsby5.5.0起支持在Head中通过html langen /、body classNamemy-body-class /设置标签属性Gatsby 会将这些属性注入最终 HTML且Head中定义的html/body会覆盖onRenderBody中setHtmlAttributes与setBodyAttributes设置的属性。标签去重Deduplication为避免head中出现重复标签可以在标签上使用id属性确保只渲染一个。看下面的例子const SEO ({ children }) ( titleHello World/title link idicon relicon hrefglobal-icon / {children} / ) export const Head () ( SEO link idicon relicon hreficon-specific-for-this-page / /SEO )这种情况下只会渲染第二个link idicon relicon hreficon-specific-for-this-page /。在一组拥有相同id的标签中最后一个生效并被写入 HTML。官方示例中的 favicon 图标即利用了这一机制首页提供默认图标{Park.name}.tsx模板页则通过 children 传入带相同idfavicon-icon的页面专属图标实现覆盖。Head 函数接收的属性Head函数会接收以下 propsGatsby Head 参考指南location.pathnameLocation 对象的 URL 路径params页面带有matchPath使用 client-only routes时的 URL 参数data通过导出的 GraphQL query 传入页面的数据pageContext创建页面时传入的上下文对象export const Head ({ location, params, data, pageContext }) ( title{pageContext.title}/title meta namedescription content{data.page.description} / meta nametwitter:url content{https://www.foobar.tld/${location.pathname}} / / )使用 Gatsby Head 的注意事项参考 Gatsby Head API 文档使用时有以下几点需要留意Head导出只能定义在页面内包括通过createPage创建的模板中不能定义在普通组件里页面卸载时 Gatsby Head 的内容会被清空因此每个页面都需要在自身的head中定义它需要的内容Head函数必须返回合法的 JSXHead函数内合法的标签为link、meta、style、title、base、script和noscriptgatsby5.6.0起Head可以访问你在wrapRootElementAPI 中定义的 React Context但wrapRootElement应只用于搭建 Context 提供者UI 组件应定义在wrapPageElementAPI 中。Rich Snippets富摘要 / 结构化数据Google 会使用网页中发现的结构化数据来理解页面内容并收集关于网页乃至整个互联网世界的信息。例如下面这段采用 JSON-LD 格式Linked Data 的 JavaScript 对象表示法的结构化数据片段可能出现在一家名为 Spooky Technologies 公司的联系页面上描述其联系信息script typeapplication/ldjson { { context: https://schema.org, type: Organization, url: https://www.spookytech.com, name: Spooky technologies, contactPoint: { type: ContactPoint, telephone: 5-601-785-8543, contactType: Customer Support } } } /script本地开发期间你可以使用 Google 的 Rich Results Test 检查是否传入了有效信息部署后Google Search Console 的富结果状态报告Rich result status reports则有助于监控页面健康状态并排查模板或服务方面的问题。进阶TypeScript 用法如果项目使用 TypeScript官方示例 examples/using-gatsby-head 提供了完整参考。与 JS 版本相比主要有三处差异配置文件gatsby-config.ts中通过import type { GatsbyConfig } from gatsby声明类型Hook 类型use-site-metadata.tsx中为useStaticQuery传入ReturnValue泛型组件类型seo.tsx中通过React.FCReact.PropsWithChildrenSEOProps描述 props页面中则用HeadFCQueryReturn类型约束Head函数。更完整的说明参见 Using Gatsby Head with TypeScript。验证与排查本地验证开发模式下访问各页面查看浏览器开发者工具中的head区域确认 title、meta description、Twitter 卡片标签是否按预期渲染同时可用 Google Rich Results Test 检查结构化数据性能审计使用 Lighthouse 审计 检查 SEO 得分部署后监控借助 Google Search Console 的富结果状态报告持续监控页面健康度。附加资源Using Gatsby Head with TypeScriptGatsby Head 参考指南Gatsby Script Component使用 Lighthouse 审计官方示例仓库examples/using-gatsby-head包含seo.tsx、use-site-metadata.tsx、{Park.name}.tsx模板页等完整实现是本文所有代码的可运行版本【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
