静态网站部署到Vercel踩坑指南：解决图片路径问题
解决后的网站：
longxiaobao.vercel.app/
前言
在将静态网站部署到Vercel时，即使本地开发一切正常，部署后却经常会遇到图片、音频等静态资源无法正常加载的问题。这是很多开发者，尤其是初次使用Vercel的开发者容易遇到的问题。本文将详细介绍如何解决这一问题，并分享在实际项目中积累的经验。
问题背景
最近在开发一个名为"龙小宝IP形象设计"的静态网站，并尝试将其部署到Vercel。网站在本地开发环境中运行良好，所有图片、音频资源均能正常显示。但是，当部署到Vercel后，发现所有静态资源都无法加载，页面上只有文字内容可见，图片区域全部显示为空白或者加载失败的图标。
问题分析
通过分析，发现导致这个问题的主要原因是路径引用方式在本地开发环境和Vercel部署环境中的解析不同：
-
本地开发环境：本地服务器（如VS Code的Live Server）通常会将项目根目录作为根路径，相对路径基于当前文件位置解析。
-
Vercel部署环境：Vercel有其特殊的目录结构和路由处理方式，特别是对于静态资源的处理。
初始配置中的问题主要包括：
- 使用了不适合的路径引用方式（例如
/public/图片.png形式的绝对路径） - vercel.json配置不正确，没有明确指定静态资源的处理方式
- 目录结构与Vercel的默认处理机制不匹配
解决方案
经过多次尝试和调整，找到了一个有效的解决方案，主要包括以下几个关键步骤：
1. 创建专用的静态资源目录
mkdir -p static && cp -r public/* static/
这一步将原来放在public目录下的所有静态资源复制到一个名为static的目录中。static是一个广泛接受的静态资源目录名称，在多种部署平台上都能得到良好支持。
2. 调整HTML文件中的资源引用路径
将HTML文件中所有的资源路径从：
<img src="/public/主视图/龙小宝主形象.png" alt="龙小宝IP形象">
修改为：
<img src="static/主视图/龙小宝主形象.png" alt="龙小宝IP形象">
注意两个关键变化：
- 路径前缀从
/public改为static - 移除了路径开头的斜杠
/，使用相对路径而非绝对路径
3. 配置vercel.json文件
创建或修改项目根目录下的vercel.json文件，确保正确处理静态资源：
{
"version": 2,
"builds": [
{ "src": "*.html", "use": "@vercel/static" },
{ "src": "static/**", "use": "@vercel/static" }
],
"routes": [
{ "src": "/static/(.*)", "dest": "/static/$1" },
{ "src": "/(.*)", "dest": "/$1" }
]
}
这个配置做了两件重要的事情：
- 在
builds部分明确指定了HTML文件和static目录下的所有文件都使用@vercel/static构建器处理 - 在
routes部分配置了路由规则，确保静态资源的请求能够正确映射到文件系统中的位置
关键经验总结
通过这次经历，总结出以下几点关于静态资源处理的关键经验：
1. 相对路径 vs 绝对路径
- 相对路径（不以
/开头）通常更可靠，因为它们不依赖于服务器的根目录配置 - 绝对路径（以
/开头）在不同环境中的解析可能不同，容易导致部署问题
2. 静态资源目录命名
- 使用通用且明确的名称如
static、assets等，而不是可能有特殊含义的名称如public - 在某些部署平台上，
public目录会被特殊处理，可能导致意外行为
3. 明确的vercel.json配置
Vercel提供了强大的配置能力，但需要正确理解和使用：
builds部分定义了如何构建项目的不同部分routes部分定义了如何处理请求路径与实际文件的映射关系- 对于静态网站，通常需要明确配置静态资源的处理方式
4. 避免中文路径问题
虽然现代浏览器和服务器对中文路径有较好的支持，但在部署环境中仍可能遇到编码问题：
- 考虑对包含中文的文件名进行URL编码
- 或者在项目结构设计时避免使用中文文件名和目录名
完整的项目结构示例
一个配置正确的静态网站项目结构应该类似于：
project-root/
├── index.html
├── static/
│ ├── images/
│ │ └── logo.png
│ ├── css/
│ │ └── style.css
│ └── js/
│ └── main.js
├── vercel.json
└── README.md
结论
Vercel是一个强大的静态网站托管平台，但正确处理静态资源路径需要对其工作机制有一定了解。通过使用适当的相对路径、创建专用的静态资源目录、正确配置vercel.json文件，可以解决绝大多数静态资源加载问题。
希望本文的经验分享能够帮助到遇到类似问题的开发者，让大家的Vercel部署之旅更加顺利！
相关资源：
