企业官网建设流程全解析

有一段时间，我们组每个人打开 Git 终端前都要先深吸一口气：仓库里既有源码又有设计源文件，还有一版接一版的视频预告。clone 一次就要拉几个 GB，CI 在每台构建机上重复下载一遍，磁盘很快吃到受不了。那时候我才下定决心把 Git LFS（Large File Storage）正式引入工作流。它的思路一句话就能说明白：把大文件的内容从 Git 对象库里挪走，只留下一个轻量的文件指针交给 Git 管理，所有二进制体积都放到配套的对象存储里。这篇文章我会从安装讲起，把 track、commit、push 的完整链路走一遍，也会把认证失败、误提交、存量仓库迁移这些常驻问题讲透。适合正在为大文件仓库体积发愁的开发者和团队负责人，按顺序照着做就好。

1. 仓库为什么会因为大文件膨胀：Git 存储模型的真相

1.1 每次提交保存的不是差异，而是完整快照

如果只用一个词描述 Git 的对象存储，我会选“快照”。每次 commit 时，Git 会把这次提交涉及的文件完整打包成一个 blob 对象，再附上 tree 对象和 commit 对象。你改了一个 500MB 的设计稿 30 次，本地.git目录里就可能躺着 30 份完整文件快照，而不是 30 个“修改了一下”的小补丁。Git 内部有 zlib 压缩和增量存储机制，但那是针对文本文件设计的，对设计稿、视频、压缩包这类本身熵很高、很难压缩的二进制文件，压缩效果和块存储的“重复率”都会大打折扣。

类比一下：你在手机相册里隔几天就存一张同一张照片的完整副本，只因为每张照片的滤镜不同。Git 对大文件的处理逻辑就是这样，它为了绝对可靠，选择了把完整内容保存下来。这个设计在文本源码上完全没问题，代码文件小、文本压缩率高，增量优化效果明显；但一碰到几个 GB 的模型权重、安装包，快照策略的成本就变得难以接受。

1.2 大文件给仓库带来的三重叠加伤害

第一重是克隆速度。仓库里的历史越久，所有大文件的历史版本都要一并下载。一个原本只有 300MB 源码的仓库，一旦混入几十个版本的设计稿和视频，clone 翻到 2GB 以上是常态，新成员入职第一件事就是等 clone，体验很差。

第二重是日常操作变慢。Git 在 diff、log、merge 时要反复读取对象，二进制文件又没法做有意义的文本对比，每次操作都要把大对象读进内存再处理。我在项目里感受最深的是：只要动过 PSD 文件，一次简单的git status都可能明显卡顿，因为过滤器要扫描工作区文件内容。

第三重是平台限制和成本。很多代码托管平台对单文件超过 100MB 就会警告，超过 1GB 甚至直接拒绝；LFS 服务会单独计费，带宽和存储量都算真金白银。如果大文件一开始就混进了普通 Git 历史，后续迁移的成本远比早点配置 LFS 要高。

1.3 Git LFS 的解决思路：指针替换与独立对象存储

Git LFS 不是把 Git 重写一遍，而是在 Git 的 clean/smudge 过滤机制上做了一层代理。当你配置好跟踪规则后，git add大文件时，clean 过滤器会把真实文件内容交给 LFS 客户端，写进仓库的历史对象里只有一段指针文本。

version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214614ab2935c943f9e0ff69b22b... size 30521

这段文本一般不到 200 字节，包含了唯一的 oid 与文件大小，真正的二进制内容被上传到远程 LFS 对象存储中。在 checkout 时，smudge 过滤器再根据指针里的 oid 把真实内容拉回来。所以你在本地工作区看到的是完整文件，而 Git 仓库内部存的是轻指针。diff、log、merge 这些操作面对的也是指针文本，自然不会再被大体积拖慢。

2. 从零装好 Git LFS：平台差异与验证要点

2.1 Windows 安装

Windows 上最省事的方式是直接下载 Git LFS 官方安装包，一路下一步就好。装的时候它会把 LFS 的过滤器和钩子注册进系统级 Git 配置，装完重开一个终端，输入git lfs version能看到版本号就行。如果你偏好命令行，也可以choco install git-lfs一步到位。装完记得重开终端，不然 PATH 没有刷新，git lfs命令会提示找不到。

我见过不少同事在这步卡住，并不是装错，而是旧终端窗口还留着原来的 PATH。另一个容易踩的点是：如果你用的是 Git for Windows 自带的 Git Bash，安装包装完会自动适配，但如果你还装了独立 Git 或 TortoiseGit，要注意 Git LFS 的安装路径是否跟默认 Git 指向一致，不然git lfs命令认不到。

2.2 macOS 和 Linux 安装

macOS 用户直接走 Homebrew 是最顺的：

brew install git-lfs

Linux 就得看发行版了。Debian/Ubuntu 上如果系统源里有 git-lfs 可以直接装：

sudo apt-get update sudo apt-get install git-lfs

但有些发行版的源里 git-lfs 版本很旧，或者干脆没有。备选方案是使用官方提供的 packagecloud 仓库脚本，添加仓库后再用包管理器安装，这样能拿到比较新的版本。CentOS/RHEL 系则对应yum install git-lfs或dnf install git-lfs。

如果服务器不方便外连，也可以从 release 页面下载对应架构的 tar.gz 包，解压后执行install.sh。这里我建议团队在内部文档里固定一个版本号，不要大家各装各的，后续排障会省很多事。

2.3 安装后的“拉起钩子”这一步别省

很多人以为装完就算完，结果一跑相关命令就报 filter 相关错误。真正该做的是在用户级别执行一次：

git lfs install

这条命令会把 pre-push、post-checkout、post-merge 等钩子安装到 Git 环境中，同时把 LFS 的 filter 配置写进~/.gitconfig。如果一个仓库是通过 clone 拉下来的，钩子通常已经就位；但如果是本机新初始化的项目，或者跳过 clone 直接把文件夹拷过来的，这步就是必需，不做的话git add时 LFS 根本不会接管文件。

2.4 用 git lfs env 做环境体检

安装完不要急着灌大文件，先跑一遍体检命令：

git lfs env

输出里会出现类似这样的关键信息：

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" git config filter.lfs.required = "true"

看到filter.lfs.required = true，说明 LFS 在你环境里处于强制开启状态。后面就算有人忘了装 LFS，克隆下来的仓库文件不会静默变成指针，而会直接报错。这个报错比悄无声息地丢文件好一百倍。我在实际项目里更喜欢这种“宁可报错也不出错”的配置，至少能第一时间发现环境问题。

3. 大文件上传的完整链路：track、commit、push 与验证

3.1 先想清楚哪些文件需要进入 LFS

最常见的清单是：二进制资源（psd、ai、sketch、figma 导出文件）、压缩包、数据集、模型权重、音频和视频素材。而像程序和纯文本源码，则保持普通 Git 跟踪即可——它们体积小、可 diff，没必要交给 LFS。不要图省事把所有.gitattributes规则都写成*，那会把仓库里所有文件全拖进 LFS，反而造成对象存储爆炸。

3.2 track 规则怎么写才不误伤文件

初始化配置和跟踪规则的命令很简单：

git lfs install git lfs track "*.psd" git lfs track "*.zip" git lfs track "assets/*" git add .gitattributes

第二条命令执行后，仓库里会出现或更新.gitattributes文件。它的内容大致是：

*.psd filter=lfs diff=lfs merge=lfs -text *.zip filter=lfs diff=lfs merge=lfs -text assets/* filter=lfs diff=lfs merge=lfs -text

注意-text这个属性，它的作用是告诉 Git 不要对二进制文件做文本转换。如果你用过.gitattributes里的text属性，应该能理解它的意义：有些二进制文件里恰好包含可以被识别为文本的字节序列，如果 Git 强行做行尾转换或 diff，文件就会被破坏。LFS 的规则里带着-text，就是在从源头避免这种问题。

写规则时还要注意通配符作用域：*.zip匹配仓库根目录和各级子目录下的所有 zip 文件，而assets/*只匹配 assets 目录一层。如果只想要某个目录下生效，写deploy/*.zip更精确。改完规则必须先把.gitattributes提交上去，否则协作者拿到的是没有规则的仓库，你一 push 大文件对方 clone 下来就是一堆指针文本。

3.3 第一次 push 大文件时的完整执行路径

配置好规则后，实际推文件的流程和普通 Git 操作几乎一样：

git add big-data.zip git commit -m "update release package" git push origin main

唯一明显的差异出现在 push 阶段。pre-push 钩子会先检查待推送的引用里有没有新的 LFS 对象，有的话先把对象上传到 LFS 存储，再推 Git 引用：

Uploading LFS objects: 100% (1/1), 212 MB

这里有个细节值得说：LFS 对象上传和 Git 引用推送是两步，而不是一次完成。所以如果 push 时网络中断，可能出现“对象已经传上去但引用没推上去”的局面。不要慌，重推一次即可，LFS 客户端会检测到对象已经存在，直接跳过上传。如果仓库里要推的 LFS 对象特别多，也可以先行单独推送对象，再推引用：

git lfs push --all origin main

这个命令在大仓库迁移时很实用，能把容易超时的对象上传和快速的引用推送分开。

3.4 如何验证大文件真正上了 LFS 存储

文件推上去之后，我习惯用三条命令确认状态：

git lfs ls-files # 查看被 LFS 接管的文件和 oid git lfs status # 查看工作区里 LFS 文件的增改状态 git cat-file -p HEAD:big-data.zip | head

前面两条看的是“LFS 视角”的状态，第三条最有意思。如果仓库里存的是普通 Git 对象，git cat-file输出的是PK之类的二进制文件头；如果被 LFS 接管了，输出就是刚才展示过的那段文本指针，以version https://git-lfs.github.com/spec/v1开头。第一次看到这个结果的时候会很直观地明白：仓库里的大文件真的变成了轻指针。

还有一个常见的验证方式是找一台没装 LFS 的机器git clone这个仓库，如果克隆下来后某些文件内容是一段文本而不是真正的二进制文件，就说明仓库引用了 LFS 对象，但当前环境没有接入客户端。这正是 LFS“指针即内容”的边界特性。

3.5 团队协作下的拉取速度优化

克隆一个 LFS 仓库时，默认只会拉取 checkout 当前分支所需的 LFS 对象，并不会把全仓库所有分支的对象都下载下来。这个设计避免了最开始的几 GB 大爆炸。但当你要切换到旧分支时，LFS 对象是延迟拉取的，首次切换可能会慢，这是正常现象。

如果确实需要把某个分支的 LFS 对象都提前拉到本地，可以：

git lfs fetch origin feature-foo

而git lfs fetch --all会把远程所有分支、标签的 LFS 对象全部拉下来，适合完整镜像仓库的场景，但代价很大，日常开发没必要。团队里如果有人机器磁盘紧张，也可以用git lfs env查看当前仓库配置的 LFS endpoint，按需调整拉取策略。

4. 真实仓库里的几个硬核问题：认证、清理、存量迁移

4.1 认证失败：git push 通了，LFS 却 403

这是我在团队里遇到最多的一个问题，现象是：git push本身正常，但 LFS 对象上传阶段报错，日志里出现Authentication required或HTTP 403 Forbidden。

原因是 LFS 上传走的是和普通 Git push 不同的 HTTP 通道。普通 push 用的凭据可能来自 SSH，也可能来自 HTTPS 缓存；而 LFS 的 batch API 是独立的一跳请求，需要服务器前置代理能识别出你的身份。很多团队习惯用 SSH 地址做远程，但 LFS 端点在认证上默认还是走 HTTPS，SSH 密钥不能直接覆盖这条链路的验证。

解决思路有这几个：

• 确认远程地址。git remote -v里如果是 SSH，检查平台是否支持 LFS over SSH 认证；如果不支持，换 HTTPS 地址。
• 配置凭据助手。用git config --global credential.helper store或者更安全的 manager 类助手，把 HTTPS 凭据缓存住，避免每次 push 都要重新输入。
• 使用个人访问令牌替代账号密码。令牌的权限范围必须包含仓库读写，很多平台允许细化 scope，如果你的令牌只开了“读源码”权限，LFS 写入自然会被拒。
• 检查git config lfs.url是否指向了错误的服务端点，尤其在公司内网自己搭了对象存储的情况下，这个配置经常被配错。

我不建议为了省事把 token 写进 remote URL，比如https://user:token@host/repo.git。虽然能跑通，但 token 会明文落在.git/config里，一旦项目被拷贝或误分享，等于把凭据暴露给所有人。

4.2 如何发现仓库里混入了不应入 LFS 的巨型 blob

最直接的体检方式是看对象库体积：

git count-objects -vH

如果显示size-pack很大，下一步就是找出重量级对象到底是谁：

git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -nr | head -20

这条命令会把历史里所有对象按大小排个序，排在前面的大对象一眼就能看出来。我常用这个方式来判断：某个几百 MB 的二进制文件是不是已经混入普通 Git 历史，而不是被 LFS 接管。

如果发现只是刚提交还没推送，处理方式很简单：git reset --soft HEAD~1把提交撤掉，重新配置 LFS 规则再 add。最麻烦的是已经推送到远程、并且其他人都基于它开发了，这时候就要用重写历史的工具。

4.3 用 lfs migrate 把存量历史搬到 LFS

如果你的仓库里已经积累了几十个版本的大文件，普通方式清理不掉，因为它们分散在历史提交里。正确做法是用 Git LFS 自带的迁移命令：

git lfs migrate info --everything

这条命令会分析所有分支和标签的历史对象，输出按扩展名分组的文件数量和总体积，帮你判断该迁移哪些类型。确认范围后执行：

git lfs migrate import --include="*.psd,*.zip" --everything

它会把所有历史提交里匹配到的文件重写为 LFS 指针，真实对象紧跟着上传到 LFS 存储。迁移完成后提交哈希会变，必须用git push --force --all推送所有分支和标签。

这个操作要选择一个团队“冻结开发”的时间点，否则有人在迁移期间提交新东西，哈希一冲突就很痛苦。迁移后在本地跑一遍git lfs fsck校验对象完整性，再让成员重新克隆。最稳妥的方式是：迁移完直接在托管平台上删除旧仓库分支的历史引用，让所有人用全新 clone 副本。

4.4 服务器端限制和预防性钩子

就算 LFS 配得再干净，平台本身的限制仍要心里有数。不少托管平台对 LFS 单文件体积有上限，常见的是 1GB 到 2GB；同时 LFS 存储和带宽有配额，超出后要么降级要么额外付费。我在项目里见过最典型的反面案例是：视频素材被当成项目资产放进 LFS，结果一次发布会视频更新就把当月带宽配额用光了。

更稳妥的做法是在仓库端提前设防线。很多团队会在pre-push或pre-commit钩子里加一层基于文件大小的校验：一旦发现超过阈值但未被.gitattributes接管的文件，直接终止提交并提示开发者。这类保护逻辑完全可以抽成一个共享脚本分发给成员，比事后清理便宜得多。

5. Git LFS 和前端 Worker 大文件上传的边界：各管一段还是二选一

5.1 别把 Git LFS 当成万能文件仓库

Git LFS 适合与仓库版本强相关的资产，但不适合处理海量用户上传文件。一个大团队如果把几万条用户上传都塞进 LFS，即使平台能撑住，clone 的带宽也会变成瓶颈。LFS 里的每个对象都会被拉取，你不可能让所有协作者把客户上传的 10GB 视频都下载一遍。

所以要先想清楚问题类型：你到底在管“版本”，还是在管“传输”？如果是前者，Git LFS 是绕不开的正解；如果是后者，得靠应用层的上传服务，前端框架也会派上用场。

5.2 前端用 Worker 做分片断点续传：为什么比直接 upload 好

最近“前端使用 Worker 上传大文件”这个方向在大文件上传场景里很热。它的核心思路是把几 GB 的文件切成若干分片，在后台线程里逐片上传，再把上传进度持久化，做到断点续传。直接在主线程用一个XMLHttpRequest或fetch上传大文件，一旦网络闪断就得全部重来，而且读取大文件、计算哈希的过程会卡住主线程，用户界面直接假死。

Worker 的结构大概是这样的：

// 主线程创建 Worker const worker = new Worker('/upload-worker.js'); worker.postMessage({ file, chunkSize: 5 * 1024 * 1024 }); // worker 内部处理分片 self.onmessage = async ({ data }) => { const file = data.file; const chunks = Math.ceil(file.size / data.chunkSize); for (let index = 0; index < chunks; index++) { const blob = file.slice(index * data.chunkSize, (index + 1) * data.chunkSize); await uploadChunk(blob, index); } };

实际操作中会比这段复杂：每个分片要计算哈希值，后端用它判断这片是否已经存在；前端把已完成的分片索引存到 IndexedDB，下次打开页面直接跳过已有分片。Worker 的价值在于 Blob 读取、哈希计算、上传队列这些重操作都在后台线程跑，页面主线程始终能响应点击和进度条更新。

5.3 选型判据与配合方案

我把两种方案的适用场景放在一起做了张表，方便直接判断：

最常见的配合模式是：项目级二进制资产走 Git LFS 进仓库，随版本走；用户上传到应用的大文件走前端分片，落进对象存储，然后在数据库里保存一张引用表。它们是两套存储体系，各自负责自己的强项，不用互相迁就。

5.4 一个小习惯

如果你负责的仓库里已经开始混入视频、数据集这类体积不小的东西，趁早把 LFS track 规则配好并提交.gitattributes。最尴尬的局面不是仓库变大，而是等你推到一半才发现规则没配、版本历史已经被污染，那时再修就难了。平时多跑一次git lfs ls-files，或者在 clone 新仓库后看一眼.gitattributes内容，几分钟时间就能避免后续几个小时的重写和协调成本。