Atlaslog / Field Notes / Build & deployment
Field note · Build & deployment
Hashed JS and CSS 404 after deploy and the page goes white
Quick answer
The build emits content-hashed filenames, and either only index.html was uploaded or the base path is wrong, so every /assets/index-8f3a2b1c.js request misses. A cached old HTML that references deleted hashes produces the same white page.
Symptom
- GET https://gis.example.cn/assets/index-8f3a2b1c.js 404 and index-2d7e9a44.css 404.
- Uncaught TypeError: Failed to fetch dynamically imported module: .../assets/map-4c1b8e2f.js.
- index.html returns 200 while every file under /assets/ returns 404.
Checklist
- Run ls dist/assets on the server to confirm the files exist.
- Compare the URLs in the served HTML with the directory listing.
- Check response headers for Age and Cache-Control to spot a cached old HTML.
- Check the build base against the deployment directory.
Fix
Point the Nginx root at dist, cache /assets/ with max-age=31536000 immutable, serve index.html with no-cache, and deploy by replacing the whole directory through a release symlink switched in one step.
Code
GET https://gis.example.cn/assets/index-8f3a2b1c.js 404 (Not Found)
GET https://gis.example.cn/assets/index-2d7e9a44.css 404 (Not Found)
Uncaught TypeError: Failed to fetch dynamically imported module:
https://gis.example.cn/assets/map-4c1b8e2f.jscurl -I https://gis.example.cn/assets/index-8f3a2b1c.js
curl -I https://gis.example.cn/ | grep -i "cache-control\|age\|etag"Watch out
- Uploading only index.html leaves all hashed assets missing even though the local build succeeded.
- Caching index.html for a year makes clients keep requesting hashes that no longer exist after the next release.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Hashed JS and CSS 404 after deploy and the page goes white. https://www.jingweizhi.com/en/cookbook/build-static-404.html (accessed 2026-11-03).