静态部署执行到一半报 Unable to resolve the source file，报错路径往往是结果，不一定是根因。先记下完整的area、theme、locale和资源相对路径，不要直接在pub/static造一个空文件蒙混过去。

沿着资源名反查所有引用

grep -R "Vendor_Module/js/missing-file" app/code app/design vendor -n
grep -R "missing-file.js" app/code app/design vendor -n

重点检查requirejs-config.js里的map、paths、deps，layout XML中的src，以及主题web目录。Linux区分大小写，开发机上的 Widget.js 与引用的 widget.js可能在生产才出错。

确认模块和主题真的存在

bin/magento module:status Vendor_Module
bin/magento theme:uninstall --help
find app/design -path '*web*' -iname 'missing-file*'

如果模块已删除但主题仍覆盖 Vendor_Module目录，或layout还引用它，清理残留覆盖。若Composer包在构建阶段被 --no-dev排除，检查该资源是不是错误放在require-dev依赖中。

只清目标，不要误删整个发布目录

rm -rf pub/static/frontend/<Vendor>/<theme>/<locale>
rm -rf var/view_preprocessed/pub/static/frontend/<Vendor>/<theme>/<locale>
bin/magento setup:static-content:deploy -f --area frontend --theme <Vendor>/<theme> <locale>

保留pub/static/.htaccess。多节点环境先在构建机生成完整静态包，校验成功后再整体发布，避免一台节点新文件、一台节点旧文件。

验证不是只看命令成功

  • 访问报错主题的首页、商品页、购物车和结账；
  • Network中JS/CSS均为200且Content-Type正确；
  • 检查静态文件签名版本已更新；
  • 切换每个部署locale；
  • 运行一次无参数的生产部署清单，确认没有其他主题引用同一缺失文件。

如果报错来自vendor文件，先核对composer.lock与vendor完整性，使用 composer install恢复包，不要直接手补vendor资源。