教程 · 编程上线
本地能跑线上 404：先查文件名大小写，再查构建产物
定位大小写、扩展名和路径别名导致的资源 404，用构建产物和大小写敏感环境验证修复。
前置：项目在本地运行正常，部署到服务器后出现资源或页面 404。
材料：项目代码、构建产物、服务器日志、Linux 容器或远程环境
材料：项目代码、构建产物、服务器日志、Linux 容器或远程环境
步骤
1. 先从报错 URL 反查文件
在浏览器网络面板找到 404 的具体地址，复制路径到项目里搜；对比实际文件名的大小写和扩展名，问题通常就藏在这几字符里。
2. 统一改成小写短横线
把文件名和引用路径统一成小写加短横线，避免大小写混用；Windows 和 macOS 默认不区分大小写，本地永远不会报错。
3. 检查构建产物里的真实路径
构建后到输出目录里找对应文件，确认它是否被输出、输出到了哪一层；路径别名配置错误时，构建能过但文件不在预期位置。
4. 在 Linux 环境验证
用容器或远程 Linux 跑一次构建和预览，或在服务器上直接访问；这是唯一能复现大小写问题的环境，本地通过不算数。
5. 加一条检查规则防复发
在提交前用脚本扫描引用路径和实际文件名是否完全匹配，或在 CI 里跑一次构建产物的链接检查；靠人记大小写，迟早还会犯。
做完检查
- 线上请求的资源全部返回 200
- 构建产物中的路径与引用完全一致
- 在大小写敏感的 Linux 环境验证通过
常见错误
- 只在 Windows 本地测试就上线
- 改了引用路径却没改文件名，或反过来
- 忽略扩展名差异，例如 .js 和 .jsx
相关工具
同类教程
密钥被打进了前端包：先分清公开变量和私密变量
识别构建时被内联到前端的变量，把密钥移到服务端并轮换已泄露的凭证。
查看 →单页应用刷新就 404：把未知路径回退到 index.html
配置服务器或托管平台的路由回退规则，让前端路由的深链接刷新和直接访问都能正常打开。
查看 →换台电脑就构建失败：锁 Node 版本再清缓存重装
用版本文件和依赖锁把本地与 CI 的 Node 版本对齐，解决因版本差异导致的构建失败。
查看 →更新时间：2026-10-29 · 平台规则/软件版本会变；操作前保留原件，以实际页面为准。
跨库学习路径
按共同关键词匹配，不是随机推荐；从任务到提示词/教程/项目继续走。