vercel.json 常用配置

🎯 引言

学完这篇文章，你将掌握项目根目录下的 vercel.json 配置文件，解决单页应用（SPA）最经典的大坑——history 路由刷新 404，并学会配置重定向和静态资源缓存。

🧱 vercel.json 是什么

到目前为止，我们的配置都在网页控制台里完成，换台电脑、换个同事就看不到了。vercel.json 是把配置写进代码仓库的方式：放在项目根目录，跟着 Git 一起走，每次部署自动生效。

{
    "rewrites": [
        { "source": "/(.*)", "destination": "/index.html" }
    ]
}

文件是标准 JSON 格式，常用的字段有三个：rewrites（重写）、redirects（重定向）、headers（响应头）。下面逐一讲解。

🪤 头号大坑：SPA 刷新 404

用 Vue Router 的 history 模式时，你一定遇到过这个问题：首页能打开，点击路由跳转到 /about 也正常，但在 /about 页面按 F5 刷新，直接 404！

原因很简单：history 模式下 /about 是前端"假装"出来的路径，服务器上根本没有 about.html 这个文件。刷新时浏览器直接向服务器要 /about，服务器找不到，只能返回 404。

解决办法就是上面的 rewrites 配置：无论请求什么路径，都返回 index.html，剩下的交给 Vue Router 在浏览器里处理。

{
    "rewrites": [
        { "source": "/(.*)", "destination": "/index.html" }
    ]
}

• source: "/(.*)"：匹配所有路径；
• destination: "/index.html"：统一返回入口文件。

提交推送后，刷新任何路由都不会再 404 了。

⚡ rewrites 和 redirects 的区别

这两个词看起来很像，但行为完全不同：

redirects 的用法示例——把旧的 /old-blog 永久跳转到 /blog：

{
    "redirects": [
        { "source": "/old-blog", "destination": "/blog", "permanent": true }
    ]
}

permanent: true 表示返回 308 永久重定向，搜索引擎会把旧链接的权重转移到新地址。

📦 用 headers 配置缓存

构建产物里的 JS/CSS 文件名带有内容哈希（如 app-a1b2c3.js），内容变了文件名就会变，非常适合强缓存：

{
    "headers": [
        {
            "source": "/assets/(.*)",
            "headers": [
                {
                    "key": "Cache-Control",
                    "value": "public, max-age=31536000, immutable"
                }
            ]
        }
    ]
}

这样用户的浏览器会把静态资源缓存一年，第二次访问几乎秒开。immutable 表示"这个文件永远不会变"，配合哈希文件名使用非常安全。

🧾 小节总结

• vercel.json 放在项目根目录，配置随仓库走，部署时自动生效。
• SPA history 路由刷新 404，用 rewrites 把所有路径指向 /index.html 解决。
• rewrites 地址栏不变，redirects 地址栏跳变，别用混。
• 带哈希的静态资源用 headers 配置一年强缓存。
• 字段按需组合，都是标准 JSON 格式。

❓ 知识问答

Q1：hash 模式的路由需要配 rewrites 吗？

A：不需要。hash 模式下路径在 # 后面（如 /#/about），浏览器不会把它发给服务器，天然没有刷新 404 问题。

Q2：rewrites 会影响 /api 接口请求吗？

A：Vercel 会优先匹配真实存在的文件和 Serverless Function，/(.*) 回退只在找不到资源时生效，所以 /api/* 接口不受影响。

Q3：vercel.json 和控制台的设置冲突了怎么办？

A：以 vercel.json 为准。建议同一项配置只在一个地方维护，推荐写进 vercel.json 跟随仓库管理。

Q4：改完 vercel.json 多久生效？

A：需要触发一次新的部署（push 或 vercel --prod），配置在部署时生效。

🧪 小练习

1. 给 vercel-demo 接上 Vue Router（history 模式），添加 /about 页面，部署后验证刷新 404 问题。
2. 添加 vercel.json 解决该问题，并为 /assets/ 目录配置强缓存响应头。

{
    "rewrites": [
        { "source": "", "destination": "" }
    ]
}

🎉 恭喜你已经掌握了 vercel.json！下一篇是课程的收官篇：用 Serverless Function 给前端项目写一个真正的后端接口。