HTML5项目在完成开发并打包发行后，出现404错误是前端部署过程中非常常见的问题，这类错误意味着客户端请求的资源在服务器上无法被找到，需要从多个维度逐一排查原因。
常见404错误触发场景
1. 静态资源路径引用错误
HTML5项目打包后，静态资源（如JS、CSS、图片）的引用路径如果配置不当，就会导致资源加载时出现404。比如开发时使用绝对路径/static/js/app.js，但部署时项目被放在服务器的子目录下，此时绝对路径会指向服务器根目录而非项目子目录，就会找不到资源。
2. 单页应用路由配置问题
使用Vue、React等框架开发的HTML5单页应用，默认使用前端路由，当直接访问非首页路由或者刷新页面时，服务器如果没有配置对应的回退规则，就会尝试查找对应的物理文件，从而返回404错误。
3. 服务器文件权限或目录配置错误
部署到服务器后，如果静态资源文件的权限设置不足，或者服务器的根目录配置没有指向项目打包后的dist目录，也会导致请求资源时返回404。
系统化排查步骤
第一步：验证本地打包结果
先在本地打开打包后的dist目录，直接双击index.html文件，查看页面是否能正常加载所有资源。如果本地打开就出现404，说明是打包配置的问题，需要检查打包工具的静态资源公共路径配置。
以Vite打包工具为例，正确的公共路径配置如下：
// vite.config.js
export default {
// 公共基础路径，子目录部署时改为对应子目录名称，如/project/
base: '/',
build: {
outDir: 'dist', // 打包输出目录
}
}
第二步：检查服务器部署路径
确认服务器上项目的部署位置，比如项目放在/var/www/html/my-project目录下，那么访问路径应该是域名/my-project/，此时打包的base配置需要改为/my-project/，否则资源会请求到根目录导致404。
第三步：配置单页应用回退规则
如果是单页应用，需要在服务器配置中所有请求都回退到index.html，由前端路由处理页面逻辑。以下是Nginx服务器的配置示例：
server {
listen 80;
server_name your_domain.com;
# 项目部署根目录，指向打包后的dist目录
root /var/www/html/my-project/dist;
index index.html;
location / {
# 单页应用回退规则，所有请求都返回index.html
try_files $uri $uri/ /index.html;
}
}
第四步：检查文件权限和服务器日志
查看服务器上静态资源文件的权限，确保Web服务器用户有读取权限，同时查看服务器的错误日志，日志中会明确记录404请求的具体路径，根据路径可以快速定位是路径错误还是文件缺失的问题。
常见问题修复示例
如果排查发现是图片资源404，首先检查图片引用路径，相对路径引用示例：
<!-- 正确的相对路径引用，相对于当前html文件位置 --> <img src="./assets/logo.png" alt="logo">
如果是history模式路由刷新404，除了配置Nginx回退规则，也可以改用hash模式路由，hash模式的路由变化不会发送到服务器，不会出现刷新404的问题，Vue Router的hash模式配置如下：
import { createRouter, createWebHashHistory } from 'vue-router'
const router = createRouter({
// 使用hash模式，路由带#号，不会触发服务器请求
history: createWebHashHistory(),
routes: [
// 路由配置
]
})
按照以上步骤逐一排查，基本可以解决HTML5源代码发行后出现的绝大多数404错误问题，排查时优先从本地打包结果和路径配置入手，再逐步检查服务器相关配置，能够快速定位问题根源。