Redwood 构建指南深入理解yarn rw build的 API 与 Web 双端生产构建流程【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本文基于 Redwood 官方文档 Builds 展开系统讲解 Redwood 框架生产构建的全过程API 侧如何被转译进./api/dist、Web 侧如何被 Vite 打包进./web/dist并顺带还原zip-it-and-ship-it在 Netlify 上的 Lambda 打包实践。读完本文你将掌握yarn rw build各选项的准确含义、底层构建任务的实际执行顺序以及如何在本地复现 Netlify 的构建与函数打包流程。构建概览一条命令两个产物目录Redwood 是一个前后端一体的全栈框架一个项目中同时包含api服务端与web浏览器端两个 side。生产构建命令将它们分别处理最终产出两套相互独立的构建产物Side构建工具产物目录产物用途apiBabel由 esbuild 驱动./api/dist服务端代码、GraphQL 服务、Serverless 函数webVite./web/dist静态资源、SPA / SSR 页面这个结论同时被 Builds 文档与 cli-commands.md 的 build 小节 明确记载We use Babel to transpile the api side into./api/distand Vite to package the web side into./web/dist.在命令行中build子命令支持限定构建范围位置参数side..表示可以传入一个数组yargs 的 variadic positional argumentsyarn rw build # 默认构建 api 与 web 两侧 yarn rw build api # 只构建 API 侧 yarn rw build web # 只构建 Web 侧 yarn rw build api web # 显式指定构建两侧对应的命令定义位于 packages/cli/src/commands/build.jscommand build [side..]description Build for production。命令还通过.middleware()检查 Node 版本版本不满足要求时会直接报错退出这是rw build在生产机与 CI 上稳定运行的第一道保障。rw build的完整参数表与 Builds 配套的 CLI 参考文档 cli-commands.md 记录了基础参数而命令的实际实现 build.js 中还包含文档表格之外的重要选项。合并两者得到完整的参数说明参数 / 选项类型默认值说明sidearray[api, web]要构建的 side可选值为api、web可同时传多个--verbose, -vbooleanfalse输出更多构建信息同时让 Listr 任务渲染器进入 verbose 模式--prerenderbooleantrueWeb 构建完成后是否执行预渲染对未标记 prerender 路由的项目会给出提示--prisma, --dbbooleantrue是否生成 Prisma Client在 api 侧存在schema.prisma且构建 api 或存在预渲染路由时生效其中--prisma与--prerender在 buildHandler.js 的 handler 签名中有默认值定义。注意一个实用的细节--prerender的默认值是true如果只想纯打包不做预渲染需要显式传--no-prerender同理--prisma对应--no-prisma。API 侧构建Babel 转译与./api/dist构建流程先清空再转译API 侧的构建入口是 packages/internal/src/build/api.ts。整个流程分为两步cleanApiBuild()直接调用fs.remove(rwjsPaths.api.dist)清空旧的./api/dist目录见 api.ts 第 38-41 行保证产物目录内不会残留上次构建的过期文件buildApi()/transpileApi()通过 esbuild 的build()API 转译全部 API 源码文件见 api.ts 第 19-26 行。值得注意的是文档中api side is transpiled by Babel的描述在实现上更精确地说应该是esbuild 负责文件遍历与打包编排Babel 负责真正的代码转换。esbuild 通过自定义插件runRwBabelTransformsPlugin见 api.ts 第 43-72 行对每个.js/.ts/.tsx/.jsx文件调用redwoodjs/babel-config提供的transformWithBabel并把转换后的代码以loader: js交还给 esbuild 输出。esbuild 关键构建选项getEsbuildOptions() 揭示了产物形态的关键约束platform: node、target: node20产物面向 Node.js 20 运行环境bundle: falseAPI 侧不做依赖打包node_modules 中的依赖在部署时按需安装或由平台处理format根据项目配置动态选择esm或cjsprojectSideIsEsm(api)即项目可以按 ESM 或 CJS 风格产出sourcemap: true同时生成.js.map外部 sourcemap 并写入sourceMappingURL注释便于线上排查错误outdir: rwjsPaths.api.dist产物统一输出到./api/dist。GraphQL Schema 校验前置步骤在真正开始转译 API 代码之前构建任务还会先执行loadAndValidateSdls对 GraphQL SDL 文件做一次校验见 buildHandler.js 第 71-74 行。如果 schema 定义存在错误构建会在产出任何 API 代码前就失败从源头拦截有问题的 GraphQL 层。Web 侧构建Vite 打包与./web/dist构建入口与两种模式Web 侧构建由独立的可执行文件 packages/vite/bins/rw-vite-build.mjs 驱动buildHandler通过execa以子进程方式调用它并把process.cwd切换到 web 目录。这样做的原因在 buildHandler.js 的注释 中写得很清楚postcss / tailwind 等工具依赖正确的 cwd 才能解析配置而把 cwd 变化隔离在子进程中可以避免影响构建进程内其他并行的任务。根据是否启用 Streaming SSR构建走两条不同路径普通 SPA 模式experimental.streamingSsr.enabled为 false调用buildWeb()即 packages/vite/src/build/build.ts 中的 buildWeb本质是调用 Vite 的build()并显式传入configFile: rwjsPaths.web.viteConfig即web/vite.config.{js,ts}与envFile: falseStreaming SSR 模式调用buildFeServer()产物面向服务端渲染场景。rw-vite-build.mjs启动时会做三重防御性检查必须传入--webDir、目录必须真实存在、目录内必须有package.json否则直接报错退出见 rw-vite-build.mjs 第 17-32 行。产物目录与 200.html 约定普通 SPA 模式下构建产物输出到./web/dist。构建完成后还有一步容易被忽略的收尾复制index.html为200.html见 buildHandler.js 第 119-129 行。这是为 Serverless / 静态托管平台的 SPA fallback 准备的——当用户直接访问/some/route这类深层路径时平台会回退到200.html再由前端路由接管。Streaming SSR 模式不使用index.html因此会跳过这一步骤。Web 构建前还会清理旧的./web/dist与web预构建目录cleanWebBuild见 build.ts 第 12-16 行确保产物干净一致。构建前的准备任务Prisma Client 与代码生成rw build不是简单地翻译源码在正式构建之前buildHandler.js 会按序执行一系列准备任务生成 Prisma Client条件--prisma开启、存在api/db/schema.prisma、且本次构建涉及 api 侧或有预渲染路由通过generatePrismaCommand构造prisma generate命令并在 api 目录执行为 GraphQL Fragments / Trusted Documents 生成类型条件redwood.toml中graphql.fragments或graphql.trustedDocuments开启调用generate()运行 codegen生成 possible types 与 trusted document store 的哈希供运行时使用。这一顺序在构建测试 packages/cli/src/commands/tests/build.test.js 中有明确断言完整任务序列为Generating Prisma Client... Verifying graphql schema... Building API... Building Web...预渲染PrerenderWeb 构建后的可选步骤当--prerender开启且构建范围包含 web 侧时构建主流程结束后会触发triggerPrerender()见 buildHandler.js 第 134-154 行它先用detectPrerenderRoutes()扫描Routes文件中标记了prerender的路由若没有任何路由标记prerender则打印提示 You have not marked any routes to prerender in your Routes并不会报错若存在预渲染路由则以独立子进程运行yarn rw prerender。之所以用独立子进程注释里给出了重要原因由于 Node 的模块缓存require module caching必须在独立进程里运行才能正确加载刚生成的 Prisma Client。对应地测试 build.test.js 第 77-92 行 验证了只构建 web 开启 prerender 无预渲染路由场景下控制台会依次打印Starting prerendering...与未标记 prerender 的警告。在 Netlify 上本地复现 Lambda 打包流程Builds 文档专门给出了在本地模拟 Netlify 构建步骤的命令这是理解 Serverless 部署形态的关键yarn rw build api cd api yarn zip-it-and-ship-it dist/functions/ zipballs/原理yarn rw build api只构建 API 侧产物位于./api/dist其中每个 GraphQL 服务、每个自定义函数都会被转译为一个独立文件放在./api/dist/functions下zip-it-and-ship-it会逐个解析dist/functions/下的 Lambda 函数文件为每个 Lambda 函数生成一个 zip 包zip 包内包含该函数运行所需的全部依赖输出到zipballs/目录。这正是 Serverless 部署的核心诉求平台只安装每个函数自己需要的依赖而不是把整个项目的node_modules都塞进去从而显著减小函数体积、加快冷启动。前置安装netlify/zip-it-and-ship-it需要作为 api side 的开发依赖安装yarn workspace api add -D netlify/zip-it-and-ship-it关于 zip 的产物最终如何被 AWS Lambda / Netlify Functions 消费可进一步参阅 deploy/serverless 文档即原文档中指向的 AWS Serverless Deploy 说明。从源码看函数的产出方式API 侧转译后的目录结构由findApiFiles()与 esbuild 的 entryPoints 决定见 api.ts 第 74-96 行所有 API 源文件都被作为独立 entry point 转译到api/dist函数目录对应api/src/functions因此每个函数在dist/functions中都有独立产物这正是 zip-it-and-ship-it 能按函数粒度打包的前提。与部署环节的衔接rw build的产物是部署的输入Redwood 针对不同平台的部署命令本质上都是先构建、再按平台规则上传/打包Serverless 平台Netlify / Vercel / AWS Lambda如上文所述API 侧按函数粒度 zipWeb 侧上传./web/dist静态资源并依赖200.html实现 SPA fallbackBaremetal / Docker 自托管需要完整的服务端产物部署模板中同样会先执行 build 步骤。Redwood 还提供了yarn rw deploy provider命令族见 packages/cli/src/commands/deploy这些命令在内部都会以rw build的产物为基础完成上传而 deploy/helpers.js 中也能看到对 build 命令的引用印证了构建是部署前置依赖这一关系。小结一次构建的全景时间线综合文档与源码一次完整的yarn rw build双端、默认参数、存在 schema.prisma实际执行的是生成 Prisma Client如需要为 Fragments / Trusted Documents 生成类型如配置开启校验 GraphQL schemaapi 侧清空并转译 API 代码到./api/distBabel esbuildNode 20 目标通过rw-vite-build.mjs子进程构建 Web 到./web/dist并复制出200.html非 SSR 模式若有预渲染路由子进程执行yarn rw prerender。如需在本地观察每一步的具体行为可加--verbose运行想跳过 Prisma Client 生成则用--no-prisma想跳过预渲染则用--no-prerender。相关源码与测试可继续深入阅读 buildHandler.js、build/api.ts、rw-vite-build.mjs 以及 build.test.js。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Redwood 构建指南：深入理解 `yarn rw build` 的 API 与 Web 双端生产构建流程
Redwood 构建指南深入理解yarn rw build的 API 与 Web 双端生产构建流程【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本文基于 Redwood 官方文档 Builds 展开系统讲解 Redwood 框架生产构建的全过程API 侧如何被转译进./api/dist、Web 侧如何被 Vite 打包进./web/dist并顺带还原zip-it-and-ship-it在 Netlify 上的 Lambda 打包实践。读完本文你将掌握yarn rw build各选项的准确含义、底层构建任务的实际执行顺序以及如何在本地复现 Netlify 的构建与函数打包流程。构建概览一条命令两个产物目录Redwood 是一个前后端一体的全栈框架一个项目中同时包含api服务端与web浏览器端两个 side。生产构建命令将它们分别处理最终产出两套相互独立的构建产物Side构建工具产物目录产物用途apiBabel由 esbuild 驱动./api/dist服务端代码、GraphQL 服务、Serverless 函数webVite./web/dist静态资源、SPA / SSR 页面这个结论同时被 Builds 文档与 cli-commands.md 的 build 小节 明确记载We use Babel to transpile the api side into./api/distand Vite to package the web side into./web/dist.在命令行中build子命令支持限定构建范围位置参数side..表示可以传入一个数组yargs 的 variadic positional argumentsyarn rw build # 默认构建 api 与 web 两侧 yarn rw build api # 只构建 API 侧 yarn rw build web # 只构建 Web 侧 yarn rw build api web # 显式指定构建两侧对应的命令定义位于 packages/cli/src/commands/build.jscommand build [side..]description Build for production。命令还通过.middleware()检查 Node 版本版本不满足要求时会直接报错退出这是rw build在生产机与 CI 上稳定运行的第一道保障。rw build的完整参数表与 Builds 配套的 CLI 参考文档 cli-commands.md 记录了基础参数而命令的实际实现 build.js 中还包含文档表格之外的重要选项。合并两者得到完整的参数说明参数 / 选项类型默认值说明sidearray[api, web]要构建的 side可选值为api、web可同时传多个--verbose, -vbooleanfalse输出更多构建信息同时让 Listr 任务渲染器进入 verbose 模式--prerenderbooleantrueWeb 构建完成后是否执行预渲染对未标记 prerender 路由的项目会给出提示--prisma, --dbbooleantrue是否生成 Prisma Client在 api 侧存在schema.prisma且构建 api 或存在预渲染路由时生效其中--prisma与--prerender在 buildHandler.js 的 handler 签名中有默认值定义。注意一个实用的细节--prerender的默认值是true如果只想纯打包不做预渲染需要显式传--no-prerender同理--prisma对应--no-prisma。API 侧构建Babel 转译与./api/dist构建流程先清空再转译API 侧的构建入口是 packages/internal/src/build/api.ts。整个流程分为两步cleanApiBuild()直接调用fs.remove(rwjsPaths.api.dist)清空旧的./api/dist目录见 api.ts 第 38-41 行保证产物目录内不会残留上次构建的过期文件buildApi()/transpileApi()通过 esbuild 的build()API 转译全部 API 源码文件见 api.ts 第 19-26 行。值得注意的是文档中api side is transpiled by Babel的描述在实现上更精确地说应该是esbuild 负责文件遍历与打包编排Babel 负责真正的代码转换。esbuild 通过自定义插件runRwBabelTransformsPlugin见 api.ts 第 43-72 行对每个.js/.ts/.tsx/.jsx文件调用redwoodjs/babel-config提供的transformWithBabel并把转换后的代码以loader: js交还给 esbuild 输出。esbuild 关键构建选项getEsbuildOptions() 揭示了产物形态的关键约束platform: node、target: node20产物面向 Node.js 20 运行环境bundle: falseAPI 侧不做依赖打包node_modules 中的依赖在部署时按需安装或由平台处理format根据项目配置动态选择esm或cjsprojectSideIsEsm(api)即项目可以按 ESM 或 CJS 风格产出sourcemap: true同时生成.js.map外部 sourcemap 并写入sourceMappingURL注释便于线上排查错误outdir: rwjsPaths.api.dist产物统一输出到./api/dist。GraphQL Schema 校验前置步骤在真正开始转译 API 代码之前构建任务还会先执行loadAndValidateSdls对 GraphQL SDL 文件做一次校验见 buildHandler.js 第 71-74 行。如果 schema 定义存在错误构建会在产出任何 API 代码前就失败从源头拦截有问题的 GraphQL 层。Web 侧构建Vite 打包与./web/dist构建入口与两种模式Web 侧构建由独立的可执行文件 packages/vite/bins/rw-vite-build.mjs 驱动buildHandler通过execa以子进程方式调用它并把process.cwd切换到 web 目录。这样做的原因在 buildHandler.js 的注释 中写得很清楚postcss / tailwind 等工具依赖正确的 cwd 才能解析配置而把 cwd 变化隔离在子进程中可以避免影响构建进程内其他并行的任务。根据是否启用 Streaming SSR构建走两条不同路径普通 SPA 模式experimental.streamingSsr.enabled为 false调用buildWeb()即 packages/vite/src/build/build.ts 中的 buildWeb本质是调用 Vite 的build()并显式传入configFile: rwjsPaths.web.viteConfig即web/vite.config.{js,ts}与envFile: falseStreaming SSR 模式调用buildFeServer()产物面向服务端渲染场景。rw-vite-build.mjs启动时会做三重防御性检查必须传入--webDir、目录必须真实存在、目录内必须有package.json否则直接报错退出见 rw-vite-build.mjs 第 17-32 行。产物目录与 200.html 约定普通 SPA 模式下构建产物输出到./web/dist。构建完成后还有一步容易被忽略的收尾复制index.html为200.html见 buildHandler.js 第 119-129 行。这是为 Serverless / 静态托管平台的 SPA fallback 准备的——当用户直接访问/some/route这类深层路径时平台会回退到200.html再由前端路由接管。Streaming SSR 模式不使用index.html因此会跳过这一步骤。Web 构建前还会清理旧的./web/dist与web预构建目录cleanWebBuild见 build.ts 第 12-16 行确保产物干净一致。构建前的准备任务Prisma Client 与代码生成rw build不是简单地翻译源码在正式构建之前buildHandler.js 会按序执行一系列准备任务生成 Prisma Client条件--prisma开启、存在api/db/schema.prisma、且本次构建涉及 api 侧或有预渲染路由通过generatePrismaCommand构造prisma generate命令并在 api 目录执行为 GraphQL Fragments / Trusted Documents 生成类型条件redwood.toml中graphql.fragments或graphql.trustedDocuments开启调用generate()运行 codegen生成 possible types 与 trusted document store 的哈希供运行时使用。这一顺序在构建测试 packages/cli/src/commands/tests/build.test.js 中有明确断言完整任务序列为Generating Prisma Client... Verifying graphql schema... Building API... Building Web...预渲染PrerenderWeb 构建后的可选步骤当--prerender开启且构建范围包含 web 侧时构建主流程结束后会触发triggerPrerender()见 buildHandler.js 第 134-154 行它先用detectPrerenderRoutes()扫描Routes文件中标记了prerender的路由若没有任何路由标记prerender则打印提示 You have not marked any routes to prerender in your Routes并不会报错若存在预渲染路由则以独立子进程运行yarn rw prerender。之所以用独立子进程注释里给出了重要原因由于 Node 的模块缓存require module caching必须在独立进程里运行才能正确加载刚生成的 Prisma Client。对应地测试 build.test.js 第 77-92 行 验证了只构建 web 开启 prerender 无预渲染路由场景下控制台会依次打印Starting prerendering...与未标记 prerender 的警告。在 Netlify 上本地复现 Lambda 打包流程Builds 文档专门给出了在本地模拟 Netlify 构建步骤的命令这是理解 Serverless 部署形态的关键yarn rw build api cd api yarn zip-it-and-ship-it dist/functions/ zipballs/原理yarn rw build api只构建 API 侧产物位于./api/dist其中每个 GraphQL 服务、每个自定义函数都会被转译为一个独立文件放在./api/dist/functions下zip-it-and-ship-it会逐个解析dist/functions/下的 Lambda 函数文件为每个 Lambda 函数生成一个 zip 包zip 包内包含该函数运行所需的全部依赖输出到zipballs/目录。这正是 Serverless 部署的核心诉求平台只安装每个函数自己需要的依赖而不是把整个项目的node_modules都塞进去从而显著减小函数体积、加快冷启动。前置安装netlify/zip-it-and-ship-it需要作为 api side 的开发依赖安装yarn workspace api add -D netlify/zip-it-and-ship-it关于 zip 的产物最终如何被 AWS Lambda / Netlify Functions 消费可进一步参阅 deploy/serverless 文档即原文档中指向的 AWS Serverless Deploy 说明。从源码看函数的产出方式API 侧转译后的目录结构由findApiFiles()与 esbuild 的 entryPoints 决定见 api.ts 第 74-96 行所有 API 源文件都被作为独立 entry point 转译到api/dist函数目录对应api/src/functions因此每个函数在dist/functions中都有独立产物这正是 zip-it-and-ship-it 能按函数粒度打包的前提。与部署环节的衔接rw build的产物是部署的输入Redwood 针对不同平台的部署命令本质上都是先构建、再按平台规则上传/打包Serverless 平台Netlify / Vercel / AWS Lambda如上文所述API 侧按函数粒度 zipWeb 侧上传./web/dist静态资源并依赖200.html实现 SPA fallbackBaremetal / Docker 自托管需要完整的服务端产物部署模板中同样会先执行 build 步骤。Redwood 还提供了yarn rw deploy provider命令族见 packages/cli/src/commands/deploy这些命令在内部都会以rw build的产物为基础完成上传而 deploy/helpers.js 中也能看到对 build 命令的引用印证了构建是部署前置依赖这一关系。小结一次构建的全景时间线综合文档与源码一次完整的yarn rw build双端、默认参数、存在 schema.prisma实际执行的是生成 Prisma Client如需要为 Fragments / Trusted Documents 生成类型如配置开启校验 GraphQL schemaapi 侧清空并转译 API 代码到./api/distBabel esbuildNode 20 目标通过rw-vite-build.mjs子进程构建 Web 到./web/dist并复制出200.html非 SSR 模式若有预渲染路由子进程执行yarn rw prerender。如需在本地观察每一步的具体行为可加--verbose运行想跳过 Prisma Client 生成则用--no-prisma想跳过预渲染则用--no-prerender。相关源码与测试可继续深入阅读 buildHandler.js、build/api.ts、rw-vite-build.mjs 以及 build.test.js。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考