Vercel 部署 Astro：10 分钟上线（2026）

静态 Astro 站部到 Vercel 是真的零配置，这一步很快。10 分钟花在 Vercel 替你猜不出来的四件事上：site 地址、trailing slash 策略、Node 版本、自定义域名的 DNS。把这四样一次配对，之后每次推代码就是一行命令上线。下面给出 Astro 5 的确切 astro.config.mjs、最小化的 vercel.json、CLI 命令，以及能真正签出 SSL 的 DNS 记录——全部按 Vercel 和 Astro 官方文档核对，数据截至 2026 年 6 月。

一句话总结

• 静态站不需要 adapter。 只有要 SSR、ISR、Vercel 图片优化或 Vercel Web Analytics 时才装 @astrojs/vercel。
• Astro 5 改成统一导入：import vercel from '@astrojs/vercel'，配 output: 'static' 或 output: 'server'。旧的 output: 'hybrid' 已经删掉——'static' 现在就涵盖混合站，单条路由用 export const prerender = false 退出预渲染。
• 在 package.json 锁 Node（"engines": { "node": "22.x" }）。Vercel 默认现在是 24.x（2026 年 2 月起），22.x、20.x 也都在支持范围内——锁版本能防止运行时被悄悄抬到新版、把上周还能过的 build 弄崩。
• 顶级域名 → A 76.76.21.21；www → CNAME cname.vercel-dns-0.com。SSL 自动签，通常几分钟内完成。
• Hobby 免费，但仅限非商业用途。 任何赚钱的站（广告、联盟、产品）都必须上 Pro，每席 $20/月。

静态还是 server：动 config 之前先定

Vercel 自动识别 Astro，把 build 命令设成 astro build、输出目录设成 dist，全程不用你手动填。唯一要你拍板的架构选择是渲染模式：

模式	output	要 adapter 吗？	适用场景
静态（默认）	'static'	不要	博客、文档、落地页、内容站
静态 + Vercel 功能	'static'	要（@astrojs/vercel）	静态站但想用 Vercel 图片优化或 Web Analytics
按需渲染（SSR）	'server'	要（@astrojs/vercel）	登录态、后台、个性化或逐请求页面

绝大多数内容站和独立项目都该用纯 'static'，而且完全不要 adapter。不需要 SSR 还硬加 adapter，只会拖慢 build，一点好处都没有。

开始前准备

• 仓库已推到 GitHub、GitLab 或 Bitbucket；Vercel 账号已关联。
• package.json 锁好 Node 版本（下面会讲）。
• 自定义域名准备好（可选，但建议现在就配，好给 SSL 留出签发时间）。

实操步骤

1. 在 astro.config.mjs 锁死关键项

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import mdx from '@astrojs/mdx';

export default defineConfig({
  site: 'https://yourdomain.com',   // sitemap + canonical 必需
  trailingSlash: 'always',          // 选一种策略，永远别混用
  build: { format: 'directory' },
  output: 'static',                 // Astro 5 里 'static' 就是默认
  integrations: [mdx(), sitemap()],
});

site 是最容易漏的一项。不配它，@astrojs/sitemap 和 canonical 标签会写成 localhost 或 *.vercel.app preview 域名，上线后悄悄毁掉 SEO。

2.（可选）vercel.json 配缓存头和跳转

{
  "cleanUrls": true,
  "trailingSlash": true,
  "redirects": [
    { "source": "/blog/:path*", "destination": "/articles/:path*", "permanent": true }
  ],
  "headers": [
    {
      "source": "/_astro/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

Vercel 自家 Astro 文档里有两条提醒：一是别用 vercel.json 给 Astro 做路径 rewrite——rewrite 只对静态文件生效、不在官方支持范围内，请改用 Astro 的 redirects 配置或 Vercel Routing Middleware；二是 vercel.json 和 astro.config.mjs 的 trailingSlash 要一致，否则会生成一大堆多余的 308 跳转。

3. 在 package.json 锁 Node 版本

{
  "engines": { "node": "22.x" },
  "scripts": {
    "build": "astro build",
    "preview": "astro preview"
  }
}

截至 2026 年 2 月，Vercel 默认构建运行时是 24.x（支持的版本线是 24.x、22.x、20.x）。engines.node 字段会覆盖项目设置里的默认值，这样即便 Vercel 把默认版本往前推，你的 build 也保持可复现。对多数 Astro 项目来说，22.x 是稳妥的当前 LTS 选择。

4. 推仓库，在 Vercel 导入

UI 路径：Add New → Project → Import。或在项目根目录用 CLI：

npm install -g vercel
vercel login
vercel link          # 把本地仓库关联到 Vercel 项目
vercel --prod        # build + 部署到生产
# Production: https://your-project.vercel.app

5. 只在要 SSR 时做（静态站跳过）

只有当你设了 output: 'server' 时，才装 adapter。Astro 5 里是单一的统一导入：

npm install @astrojs/vercel

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

如果是「大部分静态、少数动态路由」的站，就保持 output: 'static'，只在那几个页面的 frontmatter 里加 export const prerender = false;。Astro 5 会把这些路由当作 Vercel Functions 在服务端渲染、其余全部预渲染——这正是用来替代旧 'hybrid' 模式的做法。

6. 给 Production 和 Preview 配环境变量

vercel env add SITE_URL production
# https://yourdomain.com
vercel env add OPENAI_API_KEY production
# 粘贴 secret

UI：Project → Settings → Environment Variables，凡是两个环境都要用的变量，Production 和 Preview 都勾上。只留在本地 .env、没加到 Vercel 的变量，是「本地能跑、Vercel 上挂」最常见的原因。

7. 验证 build 产物 + 首次部署

npm run build
ls dist/             # 确认 sitemap-index.xml、index.html、_astro/
vercel --prod

然后打开 https://your-project.vercel.app 点几下，再用终端确认响应头和 sitemap：

curl -sI https://your-project.vercel.app/ | grep -i cache-control
curl -sI https://your-project.vercel.app/sitemap-index.xml | head -1

8. 加自定义域名和 DNS

Settings → Domains → 加 yourdomain.com。 Vercel 会显示要在 DNS 服务商处填的记录。当前通用值是：

记录类型	主机	值
A	@（apex）	76.76.21.21
CNAME	www	cname.vercel-dns-0.com

Vercel 已把推荐的 CNAME 目标从 cname.vercel-dns.com 迁到 cname.vercel-dns-0.com；旧值仍能解析，但请以你 dashboard 显示的为准。要拿项目专属记录，运行 vercel domains inspect yourdomain.com。DNS 生效后 SSL 自动签发——通常几分钟，偶尔最长一小时。

Hobby vs Pro：很多人漏掉的授权事实

Vercel 的 Hobby 计划免费，但授权范围是仅限个人、非商业用途。一旦站点开始赚钱——广告、联盟链接、付费产品，甚至是接客户的项目——Vercel 条款就要求上 Pro，每席 $20/月（见 Vercel 价格页）。纯个人博客用 Hobby 没问题；但 money page 就要把 Pro 的成本算进预算。如果「免费层不能商用」对你是硬伤，Firebase Hosting 的 Spark 免费层是允许商业用途的。

执行检查清单

• astro.config.mjs 设了 site、trailingSlash 和明确的 output。
• package.json 用 engines.node 锁 Node（"22.x"）。
• Production 和 Preview 两边都加了环境变量。
• vercel.json（如用）与 astro.config.mjs 在 trailing slash 和 cleanUrls 上一致。
• 除非 output: 'server' 或用到 Vercel 专属功能，否则不装 @astrojs/vercel adapter。
• 自定义域名显示绿勾、证书有效。
• 商业站点已切到 Pro 计划。

上线后验证

• curl -sI 在自定义 apex 域名返回 200（不是跳转死循环）。
• sitemap-index.xml 在生产 URL 可访问。
• 首次爬取后，Google Search Console 的「已提交 vs 已编入索引」数量与 sitemap 条目数对得上。
• 抽样文章 Lighthouse SEO = 100。

容易踩的坑

• astro.config.mjs 里 site 没配。 sitemap 和 canonical 写成 localhost 或 preview 域名。上线后第一个该查的就是它。
• 没用 SSR 却装了 adapter。 在 output: 'static' 的静态站上加 @astrojs/vercel 只会拖慢 build、毫无收益。不需要 SSR/ISR/Vercel 功能就删掉。
• 残留的 output: 'hybrid'。 Astro 5 删了 'hybrid'，build 会直接报错。改成 'static' + 逐路由 export const prerender = false。
• 环境变量只留在 .env。 生产会因缺变量报错。在 Vercel 里给 Production 和 Preview 都加上。
• trailing slash 设置打架。 cleanUrls: true 配 trailingSlash: 'always' 会冒出一堆 308。两个文件里统一选一种。
• 在 vercel.json 里做 rewrite。 Astro 的路径 rewrite 不受支持、行为不稳定——改用 Astro redirects 或 Routing Middleware。
• Node 被默默升版。 不写 engines.node，在 22.x 上能过的 build 可能在 Vercel 默认切到 24.x 时崩掉。

FAQ

• 一定要装 @astrojs/vercel adapter 吗？: 静态站不用。只有 output: 'server'（SSR）、ISR、Vercel 图片优化或 Vercel Web Analytics 才需要。纯静态 Astro 站零配置就能部。
• output: 'hybrid' 去哪了？: Astro 5 把它并进了 'static'。保持 output: 'static'，给需要按需渲染的路由加 export const prerender = false。残留的 'hybrid' 会让 build 失败，要删掉。
• 该锁哪个 Node 版本？: "engines": { "node": "22.x" }。Vercel 支持 24.x（2026 年 2 月起的默认值）、22.x、20.x。锁版本能在 Vercel 改默认值时保持 build 可复现。
• Vercel 会自动优化图片吗？: 会。Astro 的 Image 组件在 Vercel 上对静态站零配置按需优化；@astrojs/vercel adapter 的 imageService 选项给 SSR 提供同样能力。
• preview deploy 怎么用？: 任何分支的每次 git push 都会拿到独立 preview URL，PR 会自动评论贴出链接。preview 默认 noindex。
• 免费的 Hobby 计划能跑商业站吗？: 不能。Hobby 仅限个人、非商业用途。赚钱的站必须上 Pro，每席 $20/月。
• 不用 GitHub 能用 CLI 部署吗？: 能。项目根目录 vercel --prod 不需要任何 git remote。

相关阅读

• Vercel 是什么
• Vercel build failed 常见原因
• Vercel 内容站上线清单
• Vercel 自定义域名
• Vercel 是否适合内容站

标签: #独立开发 #Vercel #部署 / 托管 #Astro #入门 #工作流

相关文章

独立开发 / 建站指南

Vercel Edge Functions 用在内容站：2026 年还值不值

2025 年 Vercel 把 Edge 改了名，Fluid compute 又干掉了大部分冷启动。本文讲清 2026 年 6 月这套体系下，Edge 运行时在内容站还能赢的场景、什么时候该用 Node 函数、以及静态为什么常常胜过两者——附最新限制和延迟数字。

2026/05/23 #独立开发 #Vercel

独立开发 / 建站指南

Vercel ISR vs SSG 内容站怎么选

内容站在 Vercel 上该用 ISR 还是纯 SSG？从构建时间、新鲜度、函数成本、回滚四个维度讲清取舍，附 2026 年最新 Vercel 限额和可直接抄的配置。

2026/05/23 #独立开发 #Vercel

独立开发 / 建站指南

在 Vercel 上从 Turborepo monorepo 部署内容站

从 Turborepo monorepo 把内容站部到 Vercel 的精确配置：每个 app 单独的 Root Directory、turbo build、带 --fallback 的 turbo-ignore，以及不发布也能用的共享包。2026 年 6 月核实。

2026/05/23 #独立开发 #Vercel

独立开发 / 建站指南

Vercel 适合做内容站吗？（2026 费用算账）

Vercel 因 Next.js 出名，但跑 Astro 内容站也很顺。用这份 2026 年 6 月的定价算账、vercel.json 配置和图片设置来判断。

2026/05/17 #独立开发 #Vercel

独立开发 / 建站指南

Vercel build failed 怎么修：7 类原因和精确修复

Vercel "Build failed" 几乎都是 7 类原因之一：Node 版本、缺环境变量、类型错误、依赖漂移、内存不足、输出目录错、超时。按日志匹配，直接粘贴修复。

2026/05/17 #独立开发 #Vercel

独立开发 / 建站指南

Vercel 内容站上线清单（10 项检查）

截至 2026 年 6 月，Vercel 内容站上线前的 10 项检查——base URL、环境变量、www 与 apex 的 DNS、SSL、分析额度、sitemap、漏出的 vercel.app 扫描、即时回滚和花费上限。

2026/05/17 #独立开发 #Vercel