Netlify部署Next.js时@netlify/plugin-deploy-core报错的解决

报错来自@netlify/plugin-deploy-core插件的部署前置扫描环节：检测到node_modules目录下es5-ext依赖包生成的文件路径中包含#特殊字符，违反Netlify部署文件命名规则，直接阻断部署流程。这类问题通常不由业务代码改动触发，多为间接依赖版本浮动、Netlify近期更新文件扫描校验规则导致，此前构建正常的状态就是因为旧版本规则/依赖版本没有触发校验逻辑。

方案1：配置跳过node_modules扫描（推荐，无额外依赖调整成本） #

Next.js项目的实际可部署产物是构建完成后生成在.next目录下的静态资源与服务端函数，根本不需要上传本地工作目录里的node_modules文件。直接在项目根目录新增/修改netlify.toml配置，保留原有构建命令、发布目录不变的前提下，加入扫描忽略规则：

[build]
  # 原有配置全部保留，例如你原有的构建命令、发布目录不要改动
  command = "npm run build"
  publish = ".next"
  # 新增配置：让部署插件跳过node_modules目录的全量扫描校验
  ignore_node_modules = true

改完直接触发Netlify重新部署即可，这个配置不会影响Netlify环境内的依赖安装、构建流程，从根源上避开对第三方间接依赖的文件路径校验。

方案2：锁定es5-ext的稳定兼容版本 #

如果需要保持原有Netlify扫描规则的严格性，可以通过包管理器的依赖覆盖能力，把生成带#路径文件的es5-ext版本锁定到之前正常运行的旧版本。
在项目的package.json中新增overrides字段（兼容npm 8.3+、yarn 3+、pnpm所有主流版本）：

{
  "overrides": {
    "es5-ext": "0.10.62"
  }
}

操作注意事项：

• 修改完配置后，删除本地node_modules目录与对应的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装
• 本地安装完成后，检查node_modules/es5-ext目录下是否存在带#字符的文件，确认无异常后再推送代码触发Netlify部署
• 多人协作项目推送前需要同步检查锁文件的变更量，避免引发其他依赖的版本异常

方案3：临时关闭严格校验（快速兜底用） #

如果需要紧急上线，可以在Netlify项目的环境变量配置中新增变量：
NETLIFY_DEPLOY_SCAN_STRICT = false
这个配置会让部署核心插件把非法文件命名的校验结果从“阻断部署”降级为“仅告警”。注意这个方案仅适合临时应急，长期使用有隐患：如果你的实际构建产物生成了带非法字符的线上文件，访问时会出现静态资源加载失败的问题。

内容的提问来源于stack exchange，提问作者Josh Thomas