如何修复 Vercel 部署静态网站时 CSS、JS 和图片资源无法加载的问题-html教程-PHP中文网

如何修复 Vercel 部署静态网站时 CSS、JS 和图片资源无法加载的问题

Vercel 部署后页面样式丢失、脚本不执行、图片显示空白，通常是因路由配置错误导致资源请求被错误重定向至 index.html；本文详解原因定位与 vercel.json 路由规则配置方案。

vercel 部署后页面样式丢失、脚本不执行、图片显示空白，通常是因路由配置错误导致资源请求被错误重定向至 index.html；本文详解原因定位与 vercel.json 路由规则配置方案。

当你在 Vercel 上部署一个纯静态网站（如 HTML + CSS + JS + 图片）却发现样式未生效、脚本未加载、图片 404，而控制台 Network 面板中显示 /style.css 或 /img/logo.png 的响应内容竟是完整的 index.html 文本——这说明 Vercel 正在将所有请求（包括静态资源）错误地 fallback 到 index.html，而非真实提供对应文件。

根本原因在于：Vercel 默认的静态托管行为会尝试“智能匹配”文件路径，但在某些项目结构或缺失显式配置时，它可能忽略实际存在的 CSS/JS/IMG 文件，转而触发 SPA 回退逻辑（即 rewrites 或隐式 fallback: index.html），尤其当项目未包含 vercel.json 或 next.config.js 等配置文件时更易发生。

✅ 正确解决方案是：在项目根目录添加 vercel.json，明确定义静态资源路由优先级，确保 /style.css、/script.js、/img/* 等路径直接命中物理文件，仅兜底未知路径到 index.html。

以下是一个推荐的 vercel.json 配置示例（适用于标准静态站点）：

{
  "routes": [
    { "src": "/style.css", "dest": "/style.css" },
    { "src": "/script.js", "dest": "/script.js" },
    { "src": "/img/(.*)", "dest": "/img/$1" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

? 关键说明：

jm-jsjkxyjs02-zlm-405

使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。

下载

路由规则按从上到下顺序匹配，因此静态资源规则必须置于兜底规则（/(.*)）之前；
正则捕获组（如 (.*) 和 $1）确保子路径（如 /img/avatar.jpg）能正确映射到 /img/avatar.jpg；
若你使用其他资源路径（如 /css/main.css、/js/app.js、/assets/icons/），请按需扩展对应规则；
确保文件路径大小写与实际文件完全一致（Vercel 文件系统区分大小写）；
修改后需重新推送代码并触发新部署（Vercel 自动读取 vercel.json）。

? 调试建议：

打开浏览器开发者工具 → Network 标签页；
刷新页面，观察 /style.css 请求的 Response Headers 中 content-type 是否为 text/css（正常）还是 text/html（异常）；
点击该请求 → 查看 Response 内容 —— 若看到 HTML 源码，即确认被错误重定向。

⚠️ 注意事项：

不要将 vercel.json 放在子目录，必须位于项目根目录；
若项目已接入 Next.js、Astro 或其他框架，请勿手动配置 routes，应改用对应框架的静态导出或输出配置；
GitHub 仓库需确保 style.css、script.js、img/ 等文件已提交且路径与 HTML 中 / <script></script> / 的 href/src 属性严格一致（例如对应根目录下的 style.css）。