HTML5项目在本地开发时运行正常，一旦将源代码发行到测试机或生产服务器就出现白屏、脚本无响应或资源404，这类问题多数不是代码逻辑错误，而是部署环境与构建产物之间的差异被忽视。浏览器控制台里的报错信息是第一手线索，例如 Failed to load module script、404 Not Found 或 MIME type mismatch，都可以直接指向具体故障点。
一、优先检查资源路径与部署目录
本地开发时通常使用项目源码目录或开发服务器根路径，而发行后可能部署在子目录或CDN下，路径规则完全不同。如果HTML中使用了以斜杠开头的绝对路径，例如 src="/assets/main.js"，浏览器会从域名根目录请求资源，应用部署在 https://ipipp.com/app/ 时就会请求到 https://ipipp.com/assets/main.js，自然返回404。正确做法是使用相对路径，或者通过构建工具配置 publicPath、base 参数，让资源地址自动带上子目录前缀。
对于单页应用（SPA），刷新页面时服务端找不到静态文件也会导致加载失败。Nginx 可以通过 try_files 指令将请求回退到 index.html，让前端路由接管。下面是一个适配HTML5 History路由的基础配置：
server {
listen 80;
server_name localhost;
root /var/www/html5-app;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
如果项目部署在二级目录，还需要同步修改构建输出目录结构和HTML中的资源引用。例如Vite中设置 base: './'，Webpack中设置 publicPath: './' 或对应子路径，这样生成的资源地址会是相对地址，不依赖域名根路径，从而避免子目录部署时出现整片资源加载失败。
二、服务端MIME类型与跨域策略
使用ES模块的HTML5应用通常会通过 <script type="module"> 加载JavaScript。浏览器对模块脚本的MIME检查非常严格，如果服务器返回的 Content-Type 是 text/plain 或 application/octet-stream，而不是 application/javascript 或 text/javascript，脚本会被直接拒绝执行。这在IIS服务器上尤其常见，默认MIME表可能缺少 .mjs 或 .wasm 扩展名。
下面这段IIS配置可以为常用静态资源补齐正确的MIME类型：
<configuration>
<system.webServer>
<staticContent>
<remove fileExtension=".js" />
<mimeMap fileExtension=".js" mimeType="application/javascript" />
<remove fileExtension=".mjs" />
<mimeMap fileExtension=".mjs" mimeType="application/javascript" />
<remove fileExtension=".json" />
<mimeMap fileExtension=".json" mimeType="application/json" />
<remove fileExtension=".wasm" />
<mimeMap fileExtension=".wasm" mimeType="application/wasm" />
</staticContent>
</system.webServer>
</configuration>
如果资源从CDN或独立域名加载，还需要处理跨域CORS。字体文件、WebAssembly模块以及部分图片资源在跨域访问时必须返回 Access-Control-Allow-Origin 响应头，否则会被浏览器拦截。Nginx中可以针对静态资源目录添加 add_header Access-Control-Allow-Origin *;，但要注意生产环境最好将 * 替换为具体域名，避免安全风险。
三、缓存机制导致旧文件持续加载
部署新版本后仍然报错或页面功能异常，很多时候是因为浏览器或代理服务器缓存了旧的HTML和JS文件。尤其当静态资源未使用内容哈希命名时，同名文件容易被强缓存命中，用户拿到的是上一版本的代码，新接口或新依赖自然无法匹配。解决思路是让HTML文件保持短期缓存或不缓存，而为带哈希的资源文件开启长缓存。
location ~* \.(js|css|png|jpg|jpeg|gif|svg|woff2|wasm)$ {
expires 30d;
add_header Cache-Control "public, no-transform";
try_files $uri =404;
}
location ~* \.html$ {
add_header Cache-Control "no-cache, must-revalidate";
}
如果项目中注册了Service Worker，还需要检查SW脚本本身是否更新。旧版Service Worker会拦截资源请求并返回缓存内容，导致加载失败或版本滞后。可以在SW安装阶段增加 skipWaiting 和 clients.claim 逻辑，并在发布时为SW文件设置 no-cache，保证浏览器能获取到最新脚本。
四、构建产物与调试排查
当路径、MIME和缓存都排查过后，加载失败还可能与构建产物不完整有关。发行前应检查 dist 或 build 目录是否包含全部资源，尤其是动态导入生成的分包文件、sourcemap 和 asset 目录。构建工具在打包时默认会清空输出目录，但手动复制文件或增量发布时可能出现遗漏。
打开浏览器开发者工具的 Network 面板，刷新页面后按状态码筛选：404 通常表示路径错误或文件缺失；200 但资源类型不对，看 Response Headers 中的 Content-Type；请求被标记为 blocked 则检查CORS。逐条点击失败请求，在 Headers 标签里可以同时看到请求URL和响应头，对比实际部署目录能快速定位。
通过以上四个维度的排查，HTML5源代码发行后加载失败的问题大多可以解决。部署环境与本地开发环境存在差异是正常现象，把资源路径、服务端配置、缓存策略和构建产物纳入发布检查清单，能够显著降低上线后白屏和资源404的概率。