执行npm run deploy遇GitHub文件大小限制，已配Git LFS仍异常

排查&修复步骤 #

• 验证Git LFS配置有效性
  执行git lfs env查看配置输出，确认filter.lfs.process、filter.lfs.smudge、filter.lfs.clean这几项存在且指向正确的Git LFS命令。如果配置缺失，在仓库根目录执行以下命令补全：

  git config filter.lfs.process "git-lfs filter-process"
  git config filter.lfs.smudge "git-lfs smudge -- %f"
  git config filter.lfs.clean "git-lfs clean -- %f"
  

• 确认大文件被LFS正确追踪
  执行git lfs ls-files，检查目标大文件是否出现在列表中。如果没找到，重新执行追踪命令并提交规则文件：

  git lfs track "你的大文件路径/文件名"
  git add .gitattributes
  git commit -m "更新LFS追踪规则"
  

• 检查deploy脚本逻辑
  部分部署工具（如gh-pages）可能会单独处理构建目录，没有继承本地LFS配置。打开package.json查看deploy命令，比如如果是gh-pages -d dist，可以修改脚本确保LFS对象先推送：

  "deploy": "npm run build && git lfs push origin main --all && gh-pages -d dist"
  

  注意替换main为你的实际分支名。
• 重新推送LFS对象
  有时候LFS对象可能未完全上传到GitHub，执行以下命令强制推送所有LFS对象：

  git lfs push origin 你的分支名
  

• 确认GitHub仓库LFS状态
  登录GitHub仓库后台，进入「Settings」→「Git LFS」，确认LFS功能已启用，且目标大文件已存储在LFS中。

替代方案 #

如果部署工具本身不支持Git LFS，建议将大文件上传至CDN，在项目中直接引用CDN链接，避免将大文件打包进部署目录。

内容的提问来源于stack exchange，提问作者Ozod Musaev