AI AI 工具指南
独立开发 / 建站指南

Vercel 部署 Astro（10 分钟流程）

把 Astro 站部到 Vercel——附 astro.config.mjs、vercel.json、CLI 命令、SSL 验证一条龙。

发布于: 作者: AI Productivity Guide Team 🌐 查看英文版本

Astro 部署到 Vercel 真的就 10 分钟，前提是不被每个选项分心。本文走最短路径：HTTPS、自定义域名、图片优化、preview deploy 全配上，附确切的 astro.config.mjs、vercel.json 和 CLI 命令。

问题背景

Vercel 自动识别 Astro 并用合理默认值。真正要管的就两个：output 模式（static 还是 server）和 adapter（静态不要，server 用 @astrojs/vercel）。绝大多数内容站留 static 即可。

开始前准备

  • 仓库在 GitHub/GitLab/Bitbucket；Vercel 账号已关联。
  • package.json 锁 Node 版本。
  • 自定义域名准备好（可选但建议）。

实操步骤

  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',                         // 内容站
  integrations: [mdx(), sitemap()],
});
  1. 可选 vercel.json 控制缓存头、跳转、cleanUrls：
{
  "cleanUrls": true,
  "trailingSlash": true,
  "redirects": [
    { "source": "/blog/(.*)", "destination": "/articles/$1", "permanent": true }
  ],
  "headers": [
    {
      "source": "/_astro/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}
  1. package.json 锁 Node 版本：
{
  "engines": { "node": "20.x" },
  "scripts": {
    "build": "astro build",
    "preview": "astro preview"
  }
}
  1. 推仓库 + Vercel 导入。 UI（Add New → Project → import）或 CLI：
npm install -g vercel
vercel link                 # 把本地仓库关联到 Vercel 项目
vercel --prod               # 部署到生产
# Production: https://your-project.vercel.app
  1. 要 SSR（内容站很少）：
npm install @astrojs/vercel
// astro.config.mjs
import vercel from '@astrojs/vercel/serverless';

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

静态站跳过这一节。

  1. 配环境变量——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（如果都要）。

  1. 验证 build 产物 + 首次部署：
npm run build
ls dist/                                    # 确认 sitemap.xml、index.html、_astro/
vercel --prod

打开 https://your-project.vercel.app 点几下。测：

curl -sI https://your-project.vercel.app/ | grep -i cache-control
curl -sI https://your-project.vercel.app/sitemap-index.xml | head -1
  1. 加自定义域名。 Settings → Domains → 加 yourdomain.com。按提示配 DNS（典型 apex A 76.76.21.21 和 CNAME www → cname.vercel-dns.com）。SSL 自动签，< 1 小时。

执行检查清单

  • astro.config.mjs 设了 site、trailingSlash 和固定 output。
  • package.json 用 engines.node 锁 Node。
  • 环境变量同时加到 Production 和 Preview。
  • vercel.json（如用）与 astro.config.mjs 在 trailing slash / cleanUrls 上一致。
  • 自定义域名绿勾、SSL 有效。

上线后验证

  • curl -sI 主域返回 200。
  • dist/sitemap-index.xml 在生产 URL 可访问。
  • Search Console 首次爬后 “Submitted” 数与 sitemap 条目数一致。
  • 抽样 Lighthouse SEO = 100。

容易踩的坑

  • astro.config.mjs 里 site 没配——sitemap 和 canonical 写成 localhost 或 preview URL。
  • 不需要 SSR 还装了 @astrojs/vercel——build 变慢、没收益。
  • 环境变量留在 .env 没加到 Vercel——生产挂在 missing var 上。
  • build 命令在 Vercel 面板和 vercel.json 里都设了——确认哪个生效。
  • 不小心把 node_modules 推上去了——.vercelignore 或 .gitignore 解决。
  • vercel.json 开 cleanUrls: true 同时 Astro 用 trailingSlash: 'always'——会产生多余 308。统一选一种。

FAQ

  • 一定要装 @astrojs/vercel 吗？: 只有 output: 'server' 或 'hybrid' 才需要。纯静态不需要 adapter。
  • Vercel 会自动优化图片吗？: 会。Astro 的 <Image> 组件在 Vercel 部署上自动启用，或选用 @astrojs/vercel 的 image service。
  • Astro 的 preview deploy 怎么用？: 每次 git push（任何分支）都会拿到 preview URL，PR 评论自动贴出。默认 noindex。
  • 本地能 build，Vercel 上 fail 怎么办？: 通常是 Node 版本或缺环境变量。package.json engines 锁 Node 版本，看 Vercel build 日志。
  • 不用 GitHub 能用 CLI 部署吗？: 能——项目根目录 vercel --prod 不需要 git remote。

相关阅读

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

相关文章