render-static-sites

Render 静态站点

将静态前端（React、Vue、Hugo、Gatsby、Docusaurus、Jekyll 等）部署到 Render 的全球 CDN，并提供自动 TLS、Brotli 压缩、HTTP/2 和 DDoS 防护。提供免费层级。

适用场景

• 部署静态站点或 SPA（不使用服务端渲染）
• 为前端选择静态站点还是Web 服务
• 配置SPA 回退路由、重定向/重写或自定义标头
• 为静态站点设置 PR 预览环境
• 排查 CDN 托管站点上的构建失败或内容未更新问题

对于需要运行服务器的 SSR 框架（Next.js、Nuxt、SvelteKit），请改用 render-web-services。有关 Blueprint 编写，请参阅 render-blueprints。

在选择静态站点还是 Web 服务时，请阅读 references/service-types.md。

静态站点与 Web 服务

需求	使用	原因
纯 HTML/CSS/JS、SPA、文档、博客	静态站点	免费、全球 CDN、缓存即时失效
SSR（Next.js next start、Nuxt 服务器）	Web 服务	需要运行 Node/Python 等进程
从 SSR 框架导出静态站点	静态站点	如果框架支持完整静态导出（next export、nuxt generate）
API 后端	Web 服务	静态站点无法运行服务器端代码

关键限制： 静态站点不在私有网络中。它们无法通过内部主机名与其他 Render 服务通信。

构建和发布

设置	用途
buildCommand	安装依赖项并构建资源（例如 npm ci && npm run build）
staticPublishPath	要提供服务的构建输出目录（例如 build、dist、public）

Render 会自动检测并安装依赖项。设置 SKIP_INSTALL_DEPS=true，即可在构建命令中自行处理安装。

常见框架

框架	构建命令	发布路径
Create React App	npm ci && npm run build	build
Vite (React/Vue/Svelte)	npm ci && npm run build	dist
Next.js（静态导出）	npm ci && next build	out
Nuxt（静态）	npm ci && nuxt generate	.output/public
Hugo	hugo --minify	public
Gatsby	npm ci && gatsby build	public
Docusaurus	npm ci && npm run build	build
Jekyll	bundle exec jekyll build	_site
Astro	npm ci && astro build	dist

SPA 路由和重定向

单页应用需要配置一条兜底规则，让 CDN 为所有路由提供 index.html，而不是返回 404。

在控制面板（Settings > Redirects/Rewrites）中配置重定向/重写规则，或通过 Blueprint 的 routes 字段配置：

routes:
  - type: rewrite
    source: /*
    destination: /index.html

对于多路径重定向（例如旧博客 URL），请将具体规则放在兜底规则上方，以便优先匹配。

有关重定向类型、标头规则和缓存模式，请参阅 references/routing-and-headers.md。

自定义响应标头

在控制面板（Settings > Headers）中添加安全和性能标头，或通过 Blueprint 的 headers 字段配置：

headers:
  - path: /*
    name: X-Frame-Options
    value: DENY
  - path: /assets/*
    name: Cache-Control
    value: public, max-age=31536000, immutable

PR 预览

静态站点支持自动 PR 预览——每个拉取请求都会获得一个包含构建后站点的唯一 URL。

• 在控制面板中启用：Settings > PR Previews
• Blueprint：将 previews.generation 设为 automatic 或 manual
• 预览 URL 格式为 <service>-<pr-id>.onrender.com

Blueprint 配置

services:
  - type: web
    runtime: static
    name: my-frontend
    buildCommand: npm ci && npm run build
    staticPublishPath: dist
    routes:
      - type: rewrite
        source: /*
        destination: /index.html
    headers:
      - path: /*
        name: X-Frame-Options
        value: DENY
    previews:
      generation: automatic

注意： 静态站点在 Blueprint 中使用 type: web 和 runtime: static。没有单独的 type: static。

CDN 和性能

• 全球 CDN，在世界各地提供边缘缓存
• Brotli 压缩（优于 gzip）
• 默认启用 HTTP/2
• 每次部署后立即使缓存失效（零停机时间、原子部署）
• 包含 DDoS 防护

计费

静态站点有免费额度。它们会计入工作区级别的月度包含额度：

• 出站带宽（向用户提供的数据）
• 流水线分钟数（构建时间）

超出包含额度的用量可能产生额外费用。请在 Render 定价查看当前额度和费用。

参考资料

文档	内容
references/routing-and-headers.md	重定向类型、重写规则、标头模式、SPA 配置
references/framework-configs.md	10 多种框架的构建命令和发布路径
references/service-types.md	服务类型选择和执行模型

相关技能

• render-web-services — 适用于需要运行中服务器的 SSR 框架
• render-blueprints — 静态站点字段的完整 render.yaml 架构
• render-domains — 自定义域名和 TLS 设置
• render-deploy — 部署流程、CLI、MCP 操作

当前文档检索

每当此技能要求你查阅当前 Render 文档时：

1. 使用可用的 URL 获取工具或 HTTP 客户端（例如 curl）直接检索链接的 Markdown 文档。不要用网页搜索摘要代替文档。
2. 确认检索成功并返回了预期文档，然后阅读其内容。仅保存文件或输出文件路径并不足够。
3. 如果请求失败，或工具无法读取 Markdown 响应，请改为打开并阅读链接的 HTML 版本。
4. 如果两个版本都无法检索，请说明当前参考资料无法获取，并遵循技能中针对该主题的回退方案。仅将随附指南用于稳定约束，不要猜测可能变化的平台详情。

如果任务需要多个参考资料，请对每份资料都执行此流程，并区分已验证的文档和仍无法获取的文档。