「环境部署」解决在Vercel上部署中文路径资源的静态网站问题🧣
问题背景
在将一个中文电子书网站部署到Vercel时，我遇到了资源路径解析的问题。这个电子书网站包含以下特点：
- 使用中文命名的文件夹（
/书稿/）存放所有Markdown内容 - 前端使用JavaScript动态加载这些Markdown文件
- 包含相对路径引用的图片和其他资源
- 使用CSS和JS文件来实现页面样式和交互
将网站从本地环境迁移到Vercel部署时，资源无法正确加载，导致页面显示异常。
问题分析
通过分析项目结构和代码，我发现了几个关键问题：
- 相对路径问题 ：项目中使用了相对路径（如
css/style.css）而非绝对路径（/css/style.css） - 中文路径编码问题：中文路径在URL中会被编码，可能导致Vercel无法正确解析
- 客户端路由问题：单页应用(SPA)在刷新页面时，Vercel默认会尝试查找对应的物理文件
解决思路
针对这些问题，我采取了系统性的解决方案：
1. 资源路径调整
首先，我检查了整个项目中的资源引用方式，发现主要存在于三个地方：
index.html中的CSS和JS引用script.js中的Markdown文件路径- Markdown文件中对图片的引用
对于前两种情况，我决定将所有相对路径修改为绝对路径，即在路径前添加/。这样可以确保无论当前URL是什么，资源都能从网站根目录正确加载。
2. 中文路径处理
对于中文路径问题，我采取了两手准备：
- 在
script.js中使用绝对路径指向Markdown文件 - 创建
vercel.json配置文件，明确定义路由规则，确保中文路径能被正确解析
3. 客户端路由配置
为了解决SPA刷新问题，我在vercel.json中添加了一条默认路由规则，将所有未匹配的请求重定向到根目录，由前端路由接管。
实施步骤
步骤1：修改HTML文件中的资源路径
将index.html中的资源路径从相对路径修改为绝对路径：
diff
- <link rel="stylesheet" href="css/style.css">
+ <link rel="stylesheet" href="/css/style.css">
- <img src="imgic/001.png" alt="用AI释放创意封面">
+ <img src="/imgic/001.png" alt="用AI释放创意封面">
- <script src="js/script.js"></script>
+ <script src="/js/script.js"></script>步骤2：修改JavaScript中的文件路径
将script.js中所有Markdown文件路径从相对路径修改为绝对路径：
diff
- const bookOutlineFile = '书稿/书籍大纲：用AI释放创意------3天打造IP设计的终极指南.markdown';
+ const bookOutlineFile = '/书稿/书籍大纲：用AI释放创意------3天打造IP设计的终极指南.markdown';
- { title: "第一章: AI驱动的IP设计新时代", file: "书稿/第一章：AI驱动的IP设计新时代.markdown" },
+ { title: "第一章: AI驱动的IP设计新时代", file: "/书稿/第一章：AI驱动的IP设计新时代.markdown" },同时修改处理Markdown内容中图片路径的代码：
diff
- const correctedMarkdown = markdown.replace(/!\[(.*?)]\((?!\/|http)(.*?)\)/g, ``);
+ const correctedMarkdown = markdown.replace(/!\[(.*?)]\((?!\/|http)(.*?)\)/g, ``);步骤3：创建Vercel配置文件
创建vercel.json文件，定义路由规则：
json
{
"version": 2,
"routes": [
{ "handle": "filesystem" },
{ "src": "/书稿/(.*)", "dest": "/书稿/$1" },
{ "src": "/css/(.*)", "dest": "/css/$1" },
{ "src": "/js/(.*)", "dest": "/js/$1" },
{ "src": "/imgic/(.*)", "dest": "/imgic/$1" },
{ "src": "/(.*)", "dest": "/" }
]
}这个配置文件做了几件重要的事情：
"handle": "filesystem"- 首先尝试从文件系统提供文件- 针对各种资源路径定义了明确的路由规则
- 最后一条规则确保任何其他路径都重定向到首页
步骤4：添加部署文档
创建README.md文件，说明项目结构和部署步骤，方便团队成员了解项目特性和注意事项：
markdown
# 用AI释放创意------3天打造IP设计的终极指南
这是一个基于HTML、CSS和JavaScript的在线电子书项目，展示"用AI释放创意------3天打造IP设计的终极指南"的内容。
## 项目结构
- `index.html`: 主页面
- `css/style.css`: 样式文件
- `js/script.js`: JavaScript代码
- `imgic/`: 图片资源目录
- `书稿/`: 包含所有章节的Markdown文件
## Vercel部署说明
本项目已针对Vercel部署进行了优化。主要调整包括：
1. 所有资源路径都使用从根目录开始的绝对路径（如 `/css/style.css` 而非 `css/style.css`）
2. 添加了 `vercel.json` 配置文件来处理路由
3. 确保中文路径和文件名能够正确加载
### 部署步骤
1. 在Vercel上创建新项目
2. 导入此仓库
3. 无需任何特殊配置，直接部署
## 本地开发
如果需要在本地开发和测试，请使用支持静态文件服务的服务器，例如：
```bash
# 使用Python的HTTP服务器（如果已安装Python）
python -m http.server
# 或使用Node.js的http-server（如果已安装Node.js）
npx http-server注意事项
- 如果在Markdown文件中引用了图片，请确保使用相对于
书稿/目录的路径 - 中文文件名和路径在URL中会被编码，但系统会正确处理
解决效果
经过以上调整，成功解决了Vercel部署中遇到的所有问题：
- 所有资源（CSS、JS、图片）都能正确加载
- 中文路径的Markdown文件能被正确访问
- 页面刷新不会导致404错误
- 项目结构清晰，便于维护
最终的电子书网站成功部署到Vercel，用户可以通过网络访问所有内容，并享受到良好的阅读体验。
部署成功后的效果
技术要点总结
- 路径处理原则：在静态网站部署时，尽量使用绝对路径引用资源
- 中文路径处理：通过明确的路由规则解决中文路径编码问题
- SPA配置：为单页应用配置合适的路由规则，避免刷新404
- 文档化：做好项目文档，记录部署注意事项
通过这种方式，我们不仅解决了当前项目的部署问题，也提供了一个可复用的方案，可应用于其他类似的静态网站Vercel部署场景，特别是涉及非英文路径的情况。
思考与总结
这个案例告诉我们，在将静态网站部署到云平台时，需要特别注意路径处理和路由配置。特别是对于中文等非ASCII字符的处理，往往需要额外的配置和代码调整。
通过系统性思考和逐步解决各个问题点，我们最终实现了一个稳定可靠的部署方案，确保用户能够顺畅地访问电子书内容。这种解决方案不仅适用于当前项目，也为其他类似项目提供了参考模板。
适用场景
这个解决方案特别适用于以下场景：
- 包含中文或其他非ASCII字符路径的静态网站
- 基于前端路由的单页应用(SPA)
- 需要在Vercel上部署的项目
- 包含多媒体资源和复杂目录结构的网站
延伸阅读
如果您对这个主题感兴趣，可以参考以下资源进一步学习：
希望这篇文章对您有所帮助，祝您部署顺利！