最常见原因是Web服务器根目录未指向public目录，导致CSS/JS 404；需确保Nginx root或Apache DocumentRoot设为public路径，并正确执行php artisan storage:link、npm run production及清理缓存。
public目录没被Web服务器正确指向
部署后CSS/JS全部404，最常见原因是Web服务器（Nginx/Apache）没把根目录设到public，而是指向了项目根目录。Laravel所有静态资源必须通过public入口访问，否则mix.js生成的哈希文件、storage/app/public软链都会失效。
实操建议：
- Nginx配置里确认
root指向的是/var/www/your-app/public，不是/var/www/your-app - Apache需启用
mod_rewrite，且.htaccess在public目录下生效；若用虚拟主机，DocumentRoot必须设为public路径 - 运行
php artisan storage:link——这个命令只在public下建软链，如果Web根不对，链也白搭
mix.manifest.json找不到或路径错乱
使用mix()辅助函数时返回空字符串或404，大概率是mix.manifest.json缺失、位置错误，或环境变量MIX_ASSET_URL干扰了路径拼接。
实操建议：
- 检查
public/mix.manifest.json是否存在，内容是否为合法JSON（如{"/js/app.js":"/js/app.js?id=abc123"}） - 部署时别漏掉
npm run production——它生成mix.manifest.json和压缩文件，仅composer install不触发构建 - 如果用了CDN，确保
MIX_ASSET_URL环境变量值末尾**不带斜杠**（https://cdn.example.com✅，https://cdn.example.com/❌），否则会拼出双斜杠导致404
APP_URL配置影响asset()和mix()输出
asset()和mix()默认拼接APP_URL，但API项目常把APP_URL设成https://api.example.com，结果静态资源路径变成https://api.example.com/css/app.css——而API域名根本没托管前端文件。
实操建议：
- API服务不应承担静态资源分发职责；要么把前端单独部署到静态托管（如Nginx静态站、Vercel），要么在
.env里设APP_URL=https://example.com（即前端域名） - 避免在API响应中渲染含
asset()的HTML；纯API场景建议前端自己管理资源路径，后端只返回数据 - 调试时直接
dd(mix('css/app.css'))看输出，比猜更准
缓存导致旧manifest或CDN路径残留
改完配置或重新构建后样式仍不更新，可能是浏览器缓存了mix.manifest.json，或CDN缓存了HTML里已写死的资源URL（尤其用了cache:clear却没清视图缓存）。
实操建议：
- 部署后顺手跑
php artisan view:clear和php artisan config:clear，config:cache会固化APP_URL等配置，改了.env不重启PHP-FPM就无效 - 在浏览器开发者工具Network面板里点开一个CSS请求，看Headers里的
Cache-Control和实际响应内容——如果返回的是旧manifest，说明缓存没刷干净 - CDN侧要主动失效
/mix.manifest.json和HTML页面，不能只等TTL过期
真正卡住人的往往不是技术点本身，而是混合了Web服务器配置、构建流程、环境变量和多层缓存——每次只动一个变量，用curl -I查HTTP头，比反复重装快得多。
