开源 AI 生态研究项目 Git 大文件 LFS 配置教程与团队开发指南

GitHub 仓库初始化

git init
git add .
git commit -m "first commit"

关联远程仓库并推送

git remote add origin https://github.com/wang-junjian/open-ai-eco.git
git branch -M main
git push -u origin main

视频没有使用 Git LFS

remote: warning: File public/videos/open-design-webprototype.mp4 is 84.20 MB; this is larger than GitHub's recommended maximum file size of 50.00 MB
remote: warning: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
remote: warning: See https://gh.io/lfs for more information.

解决方案：

一、全局配置 public/videos/ 下所有文件走 Git LFS

1. 先安装并初始化 Git LFS（已装可跳过）

# 安装（Windows/Mac/Linux 对应安装包，命令行初始化一次即可）
git lfs install

2. 追踪 public/videos/** 全部文件

# 匹配 public/videos 下所有子目录、所有文件
git lfs track "public/videos/**"

执行后会自动生成/更新 .gitattributes 文件，内容类似：

public/videos/** filter=lfs diff=lfs merge=lfs -text

3. 把 .gitattributes 提交到仓库（必须）

git add .gitattributes
git commit -m "use LFS for all files under public/videos"

二、关键：处理已经提交到历史里视频文件（重点）

你现在仓库历史里已经存了原始大视频，只加 track 没用，历史还是臃肿，分两种场景：

刚新建仓库、还没人拉过代码

1. 删除本地+缓存里的旧大文件记录

# 递归移除整个目录所有文件的git缓存（本地文件保留，只移除git记录）
git rm --cached -r public/videos/

2. 重新 add 提交，此时会被 LFS 接管

git add public/videos/
git commit -m "move video files to LFS"
# 强制推送覆盖远程main（仅全新仓库无协作时用！多人协作禁止--force）
git push origin main --force-with-lease

三、验证是否生效

随便往 public/videos 放一个视频，执行：

git status
# 查看文件是否被LFS托管
git lfs status

正常会显示类似：public/videos/xxx.mp4 (LFS: Pointer)

四、补充说明

  1. public/videos/** 代表该目录下所有层级所有文件，不管后缀（mp4/avi/mov/png压缩包等全部走LFS）
  2. 如果只想限定视频格式，不用 **，可以写多条： 
    git lfs track "public/videos/*.mp4"
git lfs track "public/videos/*.mov"
git lfs track "public/videos/*.avi"
  3. 📌 其他开发者拉代码时，只需执行一次 git lfs install 就能自动下载LFS真实文件。

完整标准操作步骤

核心逻辑：先配置 Git LFS 再 add/提交代码，从源头不让大视频进入普通 Git 历史，彻底避免后续清理历史、强制推送的麻烦。

1. 本地新建项目文件夹，进入目录

mkdir open-ai-eco
cd open-ai-eco

2. 初始化 Git

git init

3. 安装并初始化 Git LFS（首次电脑只需执行一次）

git lfs install

4. 提前追踪视频目录（关键：在添加任何文件前配置LFS）

两种写法按需选其一

方案A：整个 videos 目录全部走LFS（推荐，简单）

git lfs track "public/videos/**"

自动生成 .gitattributes 文件，记录LFS规则。

方案B：只限定视频后缀，其他小文件不走LFS

git lfs track "public/videos/*.mp4"
git lfs track "public/videos/*.mov"
git lfs track "public/videos/*.avi"
git lfs track "public/videos/*.webm"

5. 先提交 LFS 配置文件 .gitattributes

必须优先提交规则文件，保证后续文件识别生效

git add .gitattributes
git commit -m "config git lfs for video files"

6. 再添加项目全部代码（此时 public/videos 下视频会自动转为LFS指针）

git add .
git commit -m "first commit: all source & lfs video pointers"

7. 关联远程 GitHub 仓库并推送

git remote add origin https://github.com/wang-junjian/open-ai-eco.git
git branch -M main
git push -u origin main

团队成员克隆、开发、提交流程

一、首次克隆仓库（只做一次）

1. 本地提前装好 Git LFS（必须先执行）

Windows/Mac/Linux 安装
  • Windows：下载 Git LFS 安装包，或 choco install git-lfs
  • Mac：brew install git-lfs
  • Linux：apt install git-lfs / yum install git-lfs

安装完执行全局初始化（一台电脑仅需运行1次）

git lfs install

输出 Git LFS initialized. 即成功。

2. 克隆仓库（正常 clone 即可，不用额外参数）

git clone https://github.com/wang-junjian/open-ai-eco.git
cd open-ai-eco

克隆时 Git 会自动读取仓库里的 .gitattributes，自动下载视频等LFS大文件，无需手动操作。

若克隆后视频文件夹是空/只有很小的指针文件，手动拉取LFS文件：

git lfs pull

二、日常开发、新增/修改视频文件（标准流程）

场景1：只改代码，不动视频

和平常 Git 使用完全一致，无区别

# 修改代码后
git add .
git commit -m "feat: xxx功能迭代"
git push

场景2：新增/替换 public/videos 里的视频

无需重新配置 LFS，仓库内 .gitattributes 已写好规则，add 自动识别为LFS文件

# 放入新视频后
git add public/videos/
# 或全部文件一起提交 git add .
git commit -m "add new prototype video"
git push

校验是否走了LFS（提交前可自查）

git lfs status

视频文件显示 (LFS: Pointer) = 正常； 如果显示普通文件，说明LFS未生效，检查是否执行过 git lfs install。

三、同步远程最新代码（多人协作）

拉取远端代码会自动同步LFS大文件，正常拉取即可

git pull

如果拉取后视频缺失/损坏，执行强制同步LFS资源：

git lfs pull

四、常见问题处理

  1. 报错：push 提示文件过大，GH001

    • 原因：本机没执行 git lfs install，LFS未启用，大文件当成普通Git文件提交
    • 修复： 
      git lfs install
git rm --cached 大视频文件名
git add .
git commit --amend
git push

  2. 克隆下来视频只有几KB，打不开 只是LFS指针，缺少真实文件，执行：

    git lfs pull

  3. 切换分支后视频丢失

    git checkout 目标分支
git lfs pull

五、极简总结给团队新人

  1. 电脑装 Git LFS，运行一次 git lfs install
  2. git clone 仓库地址
  3. 正常改代码、新增视频，add/commit/push 和平常一样
  4. 拉代码用 git pull，视频异常就执行 git lfs pull

相关文章