Gatsby Asset Prefix 完整指南将静态资源部署到独立 CDN 域名【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读Gatsby 构建产生的静态站点由 HTML、JavaScript、CSS、图片等资源组成默认情况下它们都被部署在同一个域名下。但在某些场景公司级托管策略、必须使用专用 CDN 分发资源等下你需要将 JS、CSS 等非 HTML 资源托管到独立域名。本指南基于 asset-prefix.md 官方文档结合 Gatsby 仓库源码系统讲解assetPrefix的配置方式、--prefix-paths构建标志的作用、双域名部署方案以及与pathPrefix、gatsby-plugin-offline的组合使用要点。读完本文你将能独立完成HTML 与静态资源分离托管的完整部署链路。什么是 Asset PrefixGatsby 生成的静态内容HTML 文件、JavaScript、CSS、图片等可以以极低成本在任何地方大规模托管。默认情况下这些内容都从同一个域名提供。assetPrefix是一个gatsby-config.js配置项它让 Gatsby 在构建时把非 HTML 资源JavaScript、CSS、图片等的引用路径加上一个前缀域名从而让这些资源可以从独立的 CDN 域名加载而 HTML 等核心文件仍然托管在你的主域名上。典型使用场景公司规定静态资源必须走专用 CDN需要遵循企业特定的托管安全与合规策略希望通过 CDN 就近分发资源、减轻主站带宽压力。配置与启用两步完成 Asset Prefix第一步在gatsby-config.js中添加assetPrefix在站点根目录的gatsby-config.js中配置module.exports { assetPrefix: https://cdn.example.com, }从源码看assetPrefix的值在构建期会经过 Joi Schema 校验见 packages/gatsby/src/joi-schemas/joi.ts它被stripTrailingSlash处理自动去除末尾斜杠并且要求是合法的 URIallowRelative: true允许相对路径形式的 assetPrefix例如/assets但不推荐在生产环境使用。配置值最终会被写入 Gatsby 的 Redux storeconfig状态供 webpack 等模块读取见 packages/gatsby/src/utils/webpack.config.js。第二步构建时必须显式开启前缀关键点仅配置assetPrefix还不够。你必须显式启用前缀否则构建会忽略该选项按资源与 HTML 同域的方式正常输出。启用方式二选一gatsby build --prefix-pathsPREFIX_PATHStrue gatsby build只有带上了--prefix-paths标志或PREFIX_PATHStrue环境变量Gatsby 才会把资源路径前缀应用到构建产物上。这一点可以从底层getPublicPath的实现得到印证——该函数只有在prefixPaths为真且配置了assetPrefix或pathPrefix时才返回前缀字符串否则返回空字符串见 packages/gatsby/src/utils/get-public-path.ts。完成以上两步后你的应用就具备了核心文件托管在主域名、静态资源从 CDN 加载的部署形态。构建产物与双域名部署构建后资源引用长什么样启用前缀后所有静态资源的引用都会被自动加上assetPrefix。例如原本的 JS 文件app-common-1234.js在生成的 HTML 中会是script srchttps://cdn.example.com/app-common-1234.js/script在 webpack 层getPublicPath({ assetPrefix, pathPrefix, ...program })的返回值被用作 webpack 的output.publicPath见 packages/gatsby/src/utils/webpack.config.js因此 chunk、图片等所有经 webpack 处理的资源都会带上该前缀。部署要点public目录要同时发布到两个地方重要提醒构建后的资源引用指向 CDN因此如果只把产物部署到主域名资源将无法加载。通用做法是把构建生成的public目录内容同时部署到主域名和 CDN/asset prefix 指向的位置——HTML 文件由主域名提供其余资源由 CDN 提供。方式一使用onPostBuildAPI 钩子Gatsby 暴露了onPostBuildAPI 钩子构建完成后会执行你可以在这里把public目录的内容同步/上传到 CDNconst assetsDirectory public exports.onPostBuild async function onPostBuild() { // do something with public // e.g. upload to S3 }方式二使用package.jsonscripts也可以借助 npm 脚本在构建完成后调用命令行工具完成资源目录的部署。下面示例用aws-cli把public目录同步到 S3 bucket{ scripts: { build: gatsby build --prefix-paths, postbuild: aws s3 sync public s3://mybucket } }npm 的生命周期机制保证每当执行npm run build时postbuild脚本会在构建完成后自动运行从而在构建结束时把带前缀的资源发布到独立域名上。进阶组合与其他特性的协同与pathPrefix组合使用pathPrefix功能与assetPrefix相关但不同它给所有站点内容加一个统一前缀路径例如把博客托管在/blog而不是项目根路径。assetPrefix与pathPrefix可以无缝协同构建时同样使用--prefix-paths标志即可实现核心功能位于某个路径前缀之下、资源托管在 CDN的部署形态。两者的拼接逻辑在源码中有清晰实现getPublicPath会把assetPrefix与pathPrefix分别去除首尾斜杠后用/连接见 packages/gatsby/src/utils/get-public-path.ts对应的单元测试验证了https://cdn.example.com/blog这类组合结果见 packages/gatsby/src/utils/tests/get-public-path.ts。需要注意的校验约束当同时配置assetPrefix与pathPrefix时Gatsby 会要求assetPrefix必须是绝对 URI如https://cdn.example.com否则抛错 assetPrefix must be an absolute URI when used with pathPrefix见 packages/gatsby/src/joi-schemas/joi.ts。原因是相对路径的 assetPrefix 无法与 pathPrefix 正确拼合出可用的 URL。与gatsby-plugin-offline组合使用使用自定义 asset prefix 时gatsby-plugin-offline仍然可以为资源提供离线缓存能力但需要满足以下条件CORS 头配置资源服务器CDN需要设置Access-Control-Allow-Origin响应头值可以是*或你站点的来源origin否则跨域资源无法被 service worker 正常抓取与缓存。关键资源必须保留在内容服务器主域名上sw.js本身以及需要预缓存的资源——webpack bundle、app bundle、manifest以及其中引用的任何图标、离线插件 app shell 的资源都必须能从内容服务器获取到。你可以在生成的sw.js中通过查找self.__precacheManifest变量找到这些预缓存资源列表。如果配置了manifest.webmanifest记得把其中引用的图标也一并保留在主域名。要验证 service worker 是否正常工作可以在浏览器开发者工具中打开Application → Service Workers面板查看并在Console / Network面板检查是否有加载失败的资源。小结assetPrefix是 Gatsby 将静态资源与 HTML 分离托管的官方方案完整落地需要三步在gatsby-config.js中配置assetPrefix建议使用绝对 CDN URL构建时显式传入--prefix-paths或设置PREFIX_PATHStrue将public目录同时发布到主域名与 CDN可通过onPostBuild钩子或postbuildnpm 脚本自动化。在此基础上你可以放心地与pathPrefix注意 absolute URI 约束和gatsby-plugin-offline注意 CORS 与预缓存资源组合使用构建出核心文件与资源完全分离、CDN 加速、离线可用的生产级 Gatsby 应用。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考