文件相关问题

文件名大小写问题

注意

Windows 下文件名不区分大小写，但 Linux 服务器区分大小写！

问题表现：

• Windows 本地开发正常
• 部署到 Linux 服务器后出现 404

解决方案：

• 统一使用小写文件名和文件夹名
• 链接路径与实际文件名保持一致

示例：

❌ 错误：文件名是 MyFile.md，链接写成 /myfile
✅ 正确：文件名和链接都用 myfile.md

最佳实践：

1. 文件名全部使用小写
2. 使用连字符 - 分隔单词，如 my-file.md
3. 避免使用空格和特殊字符
4. 中文文件名需要 URL 编码，建议用英文

图片不显示

可能原因：

1. 图片路径错误
2. 图片文件名大小写不匹配
3. 图片未放在正确的目录

解决方案：

方案 1：使用 public 目录（推荐）

<!-- 图片放在 docs/public/images/ -->
![图片](/images/example.png)

方案 2：使用相对路径

<!-- 图片与 markdown 文件在同一目录 -->
![图片](./example.png)

<!-- 图片在上级目录的 images 文件夹 -->
![图片](../images/example.png)

注意事项：

• public 目录中的文件会被复制到输出根目录
• 相对路径的图片会被 Vite 处理和优化
• 确保图片文件名大小写与引用一致

文件找不到 404

排查清单：

• [ ] 文件是否真实存在
• [ ] 文件路径是否正确
• [ ] 文件名大小写是否匹配
• [ ] 是否在 .gitignore 中被忽略
• [ ] 是否正确部署到服务器

常见错误：

❌ /web/vitepress/index.md  # 不要加 .md 后缀
✅ /web/vitepress/          # 自动对应 index.md
✅ /web/vitepress/index     # 也可以这样写