开发机页面正常，生产执行 setup:static-content:deploy 却报 Unable to resolve the source file。这类错误往往被“删除 pub/static 再试”暂时掩盖，真正原因是某个资产引用无法沿模块和主题回退链找到文件。

完整路径决定排查方向

保存错误中请求的逻辑路径、area、theme 与 locale。Vendor_Module::images/a.svg 走模块资源解析；css/source/_extend.less 走主题继承；相对 import 又以当前 Less 文件为基准。不要只复制最后的文件名。

Linux 大小写会揭露本地错误

Windows/macOS 开发环境可能容忍 Logo.svg 与 logo.svg，Linux 生产会认为是不同文件。检查 Git 中真实大小写，并用一次明确 rename 提交修复；只在本地改大小写有时不会进入版本记录。

git ls-files | grep -i 'logo.svg'
bin/magento dev:source-theme:deploy --type=less frontend/Vendor/theme

第二条命令是否可用取决于版本和模式，生产部署仍应使用正式静态内容命令。

主题父级和模块依赖

theme.xml 的 parent 指向未安装主题，或 composer 包在生产被排除，回退链会中断。确认模块在 app/etc/config.php 启用，资源文件确实进入当前 release。代码引用另一个模块资产时，模块依赖也应在 module sequence/composer 中明确。

locale 并不只是翻译

只部署 en_US，store 使用 zh_Hans_CN 时，某些本地化静态文件和 JS 翻译可能缺失。确认部署命令覆盖实际启用 locale。不要无差别部署所有语言来逃避配置问题，这会显著延长发布时间和占用磁盘。

Less import 最容易留下相对路径

扩展升级后移动了变量文件，旧主题仍 import 原路径。搜索整个代码库中的报错路径，确认来源是自定义主题而非生成文件。不要直接编辑 pub/static 或 var/view_preprocessed，它们下次部署会重建。

修复后在干净构建目录对所有生产主题和 locale 部署，确认命令返回成功，再原子切换 release。前台至少检查首页、分类、商品、结账和后台登录，避免“命令成功但关键 bundle 缺失”。

并行部署要注意共享目录

多台机器同时向同一个 pub/static 写入，可能一台清理而另一台仍在复制，最终留下混合版本。更安全的方式是在独立 release 目录完成构建，校验文件清单后一次切换软链接或发布到对象存储。静态签名版本应与文件集合同时更新，避免 HTML 指向尚未上传完成的新版本。