企业官网建设流程全解析

• 后端
• 前端
• Web框架
• 开发工具

Render 是一站式云平台，可构建并运行应用与网站，提供免费 SSL、全球 CDN、私有网络以及从 Git 仓库自动部署的能力，并且自带数据库。本文以 Redwood 官方部署文档 docs/docs/deploy/render.md 为主体，结合本仓库中setup deploy render与deploy render两条 CLI 命令的真实源码实现，完整讲解如何在 Render 上以 Serverful（常驻服务）方式部署一个 Redwood 应用——包括渲染蓝图render.yaml的逐段解读、Postgres/SQLite 数据库的接入方式、健康检查函数的自动生成，以及首次部署后必须手动完成的 API 重写规则修正。读完本文，你将能独立把一个新的 Redwood 项目推送到 Render 并稳定运行。

Render 与 Redwood 的部署模型

Render 的核心定位是“unified cloud”——把构建、托管、数据库、CDN、SSL 都收敛到一个平台。对 Redwood 而言，Render 属于Serverful 部署（常驻 Node 进程），这与 Netlify/Vercel 等纯 Serverless 平台形成对比：API 侧在 Render 上是一个常驻运行的 Node 服务，而不是按请求冷启动的函数。

一个 Redwood 应用在 Render 上通常被拆成两个服务：

• web 服务：类型为static，构建后发布web/dist静态产物，由 Render 的 CDN 与重写规则提供服务；
• api 服务：类型为node，常驻运行 Fastify 服务器，承载 GraphQL 端点与所有函数（Functions）。

两者之间通过 Render 的rewrite路由把/.redwood/functions/*的请求转发到 API 服务的真实地址，从而让前端与后端看起来“同源”。

快速上手：Render tl;dr 部署四步走

原文档给出了一条最直接的体验路径，完整命令如下：

第 1 步：创建项目

yarn create redwood-app ./render-deploy

第 2 步：初始化 Git 并推送到远端仓库

项目安装完成后，进入目录执行：

git init git add . git commit -m "initial commit"

然后将其作为一个新仓库推送到 GitHub 或 GitLab（Render 支持从这两个平台拉取代码并自动部署）。

第 3 步：运行 Render 部署设置命令

yarn rw setup deploy render

该命令会生成 Render 蓝图配置文件render.yaml、更新redwood.toml中的 API 地址，并自动添加一个健康检查函数。--database标志用于选择数据库方案：

例如使用 SQLite 时执行：

yarn rw setup deploy render --database sqlite

第 4 步：在 Render 控制台完成部署

将render.yaml提交到仓库并推送到 GitHub/GitLab 后，登录 Render 控制台，选择 Blueprint（IaC）方式关联该仓库，Render 会依据render.yaml自动创建 web、api 以及数据库服务。详细的平台侧操作可参考 Render 官方的 Redwood 部署文档。

深入源码：setup deploy render到底做了什么

原文档对这条命令只给了概要，但本仓库的源码完整揭示了它的四个任务。命令入口位于 packages/cli/src/commands/setup/deploy/providers/render.js，其handler通过 Listr 任务链依次执行：

1. Adding render.yaml——调用getRenderYamlContent(database)生成蓝图文件；
2. Updating API URL in redwood.toml——把[web]下的apiUrl改写为/.redwood/functions；
3. 添加健康检查函数——写入api/src/functions/healthz.js；
4. 打印后续指引——提示创建 Render 账号、阅读官方部署文档，并特别提醒首次部署后要更新render.yaml中的重写目标地址。

--database参数的取值与校验逻辑

builder中定义了参数（同见 providers/render.js）：

yargs.option('database', { alias: 'd', choices: ['none', 'postgresql', 'sqlite'], description: 'Database deployment for Render only', default: 'postgresql', type: 'string', })

当选择postgresql或sqlite时，getRenderYamlContent会先读取api/db/schema.prisma，通过 Prisma 解析出当前的数据源 provider（config.datasources[0].activeProvider），并与命令行传入的--database比对：

• 若一致，则生成对应数据库配置的render.yaml；
• 若不一致，命令会直接报错并给出两条解决路径：要么修改schema.prisma的 provider 后重新执行yarn rw prisma migrate dev与 setup 命令，要么改用与 schema 匹配的--database取值（见 providers/render.js）。

这意味着--database的选择必须与项目的 Prisma 数据源一致，否则命令会拒绝执行，而不是生成一份无法运行的配置。

redwood.toml的apiUrl更新机制

updateApiURLTask（实现在 packages/cli/src/commands/setup/deploy/helpers/index.js）会读取根目录redwood.toml并分三种情况处理：

1. 已存在apiUrl：用正则替换整行为apiUrl = "/.redwood/functions"；
2. 不存在apiUrl但存在[web]段：在[web]下新增该行；
3. 两者皆无：在文件末尾追加[web]段与apiUrl。

这个值让前端在浏览器中通过同源路径/.redwood/functions访问 API，再由 Render 的 rewrite 规则转发到真实的 API 服务地址，从而规避跨域（CORS）问题。

自动生成的健康检查函数

命令还会写入 api/src/functions/healthz.js，其内容来自模板RENDER_HEALTH_CHECK（见 templates/render.js）：

// render-health-check export const handler = async () => { return { statusCode: 200, } }

该函数用于 Render 对 API 服务做健康探测，保证常驻进程被判定为“存活”。

蓝图解析：render.yaml的每一段含义

render.yaml的生成模板定义在 packages/cli/src/commands/setup/deploy/templates/render.js，其中服务名取自项目目录名（path.basename(getPaths().base)）。以下是一个--database postgresql场景下生成的完整蓝图（项目名以render-deploy为例）：

services: - name: render-deploy-web type: web env: static buildCommand: corepack enable && yarn install && yarn rw deploy render web staticPublishPath: ./web/dist envVars: - key: SKIP_INSTALL_DEPS value: true routes: - type: rewrite source: /.redwood/functions/* # Replace `destination` here after your first deploy: # # ``` # destination: https://my-redwood-project-api.onrender.com/* # ``` destination: replace_with_api_url/* - type: rewrite source: /* destination: /200.html - name: render-deploy-api type: web plan: free env: node region: oregon buildCommand: corepack enable && yarn install && yarn rw build api startCommand: yarn rw deploy render api envVars: - key: DATABASE_URL fromDatabase: name: render-deploy-db property: connectionString databases: - name: render-deploy-db region: oregon

逐段解读如下：

• web 服务：env: static表明这是静态站点；buildCommand先启用 corepack、安装依赖，再执行yarn rw deploy render web（等价于安装依赖 +yarn rw build web --verbose，见下文）；staticPublishPath: ./web/dist指定发布目录；SKIP_INSTALL_DEPS: true避免 Render 重复安装依赖。
• 路由重写：第一条 rewrite 把/.redwood/functions/*转发到 API 服务；第二条 rewrite 把所有路径回退到/200.html，这是 SPA 路由（如 React Router）能正常工作的关键——刷新任意前端路径都不会 404。
• api 服务：env: node常驻运行 Node 进程；plan: free使用免费套餐；region: oregon指定区域；startCommand启动yarn rw deploy render api。
• 数据库：fromDatabase引用同文件下定义的databases，Render 会自动创建 Postgres 实例并把连接串注入DATABASE_URL环境变量。

重要的首次部署注意事项：web 服务的destination: replace_with_api_url/*是一个占位符。首次部署完成后，API 服务会获得一个形如https://my-redwood-project-api.onrender.com的真实地址，必须把该占位符替换为这个真实 URL，否则前端的函数请求无法命中 API 服务。这也是 setup 命令结束后打印提示中特别强调的一条。

SQLite 模式下的蓝图差异

若使用--database sqlite，API 服务段会替换为（见 templates/render.js）：

envVars: - key: DATABASE_URL value: file:./data/sqlite.db disk: name: sqlite-data mountPath: /opt/render/project/src/api/db/data sizeGB: 1

SQLite 不需要独立数据库实例，而是通过 Render 的持久化磁盘（disk块，默认 1GB）挂载到api/db/data目录，DATABASE_URL直接指向file:./data/sqlite.db，从而保证重启后数据不丢失。

部署命令：yarn rw deploy render <side>的执行细节

render.yaml的buildCommand与startCommand都调用了部署命令deploy render，其实现位于 packages/cli/src/commands/deploy/render.js。命令签名为render <side>，side可选api或web，另有两个布尔选项：

API 侧的执行流程

yarn rw deploy render api依次完成：

1. 数据库迁移：若--prisma为真，运行prisma migrate deploy --schema "api/db/schema.prisma"，将 schema 变更应用到 Render 上的真实数据库；
2. 数据迁移：若--data-migrate为真，先检查根package.json的 devDependencies 中是否有@redwoodjs/cli-data-migrate包。没有该包时会跳过并打印提示——建议执行yarn add -D @redwoodjs/cli-data-migrate，因为缺少它容易在部署时遇到内存问题；存在则运行yarn rw dataMigrate up；
3. 启动服务器：检查api/dist/server.js是否存在（即是否配置了自定义 server file）。存在则以yarn node启动该文件；否则动态导入@redwoodjs/api-server的apiCLIConfigHandler并按 Redwood 默认配置启动 Fastify API 服务器。

此外，源码在文件顶部有一个细节：当命令带api参数时会预先设置REDWOOD_DISABLE_TELEMETRY=1（见 deploy/render.js），注释解释了原因——API 侧在 Render 免费套餐上很容易超出资源限制，因此需要关闭 telemetry 中间件来省下这部分开销。

Web 侧的执行流程

yarn rw deploy render web相对简单，执行两步：先yarn install安装依赖，再yarn rw build web --verbose输出详细构建日志，构建产物落在web/dist，由 Render 静态托管。

部署后的验证与排障要点

完成部署后，建议按以下顺序验证：

1. 打开 web 服务域名，确认首页与 SPA 内路由可正常访问（对应 rewrite 到/200.html的规则生效）；
2. 验证 API 可达：访问https://<your-web-app>/ .redwood/functions/healthz（实际路径去掉空格），应返回 200；同时确认/.redwood/functions/graphql能被转发到 API 服务；
3. 检查render.yaml的 destination：若前端能打开但所有 API 请求失败，绝大多数原因是destination: replace_with_api_url/*尚未替换为真实 API 地址，此时回到仓库修改该值并推送，Render 会自动重新部署；
4. 确认数据库连接：在 Render 控制台查看 API 服务的日志，若出现连接错误，检查DATABASE_URL是否已由fromDatabase正确注入。

小结

Render 为 Redwood 提供了一条 Serverful 部署路径：通过yarn rw setup deploy render一条命令即可生成包含 web 静态服务、api 常驻服务与数据库定义的render.yaml蓝图，配合yarn rw deploy render <side>完成构建、迁移与启动。本文结合 providers/render.js、templates/render.js 与 deploy/render.js 的源码，把原文档的快速上手步骤展开到了文件级细节。唯一的“手动步骤”是首次部署后更新render.yaml中的 API 重写目标——记住这一点，整个部署流程即可无缝跑通。

• 后端
• 前端
• Web框架
• 开发工具