Docker+Nginx环境下Git LFS追踪文件仍以指针形式提供的问题

我们使用Docker、Nginx和GitHub托管Unity WebGL项目，多个构建版本存放在projects目录下。切换到Git LFS并向handfan项目提交大文件后，Unity加载器出现异常——卡在加载界面，浏览器报以下错误：

• SyntaxError: Unexpected identifier 'https'
• ReferenceError: Can't find variable: createUnityInstance

访问https://<domain>/handfan/Build/handfan.loader.js时，返回的是Git LFS指针而非实际JS内容：

version https://git-lfs.github.com/spec/v1
aid sha256:...
size 18903

这是Git LFS追踪文件无法正常加载的典型案例，尽管该JS文件存入LFS并不合理，但需解决当前部署问题。

部署环境 #

• Unity WebGL构建产物提交至GitHub仓库
• handfan/Build/下所有构建文件均由Git LFS追踪
• 使用webhook容器，仓库更新时自动执行git pull及deploy.sh部署脚本
• Nginx容器基于nginx:alpine镜像，通过宿主机挂载webhook容器的构建目录，从/usr/share/nginx/html提供静态服务
• Git仓库克隆至webhook容器的/data/repo目录，包含多个项目构建版本（如projects/webData、projects/otherWebData）
• 每个项目对应独立的Nginx实例

已尝试操作 #

• 确认webhook容器已安装Git LFS
• git lfs install、git lfs fetch、git lfs pull执行无报错
• 尝试过git lfs checkout及git lfs pull --include="*"
• 确认Nginx可正常提供同一卷下非LFS构建版本（如/lulu）的服务
• 本地托管构建版本可正常运行
• 检查webhook和Nginx容器内的handfan.loader.js，均显示Git LFS指针
• docker-compose.yml中的卷挂载配置无误
• LFS拉取后重建并重启容器

部署脚本deploy.sh内容 #

#!/bin/bash

REPO_URL="git@github.com:<your-org>/<your-repo>.git"
REPO_DIR="/data/repo"

cd "$REPO_DIR" || exit

echo "Checking Git LFS..."
git lfs version || { echo "Git LFS not installed"; exit 1; }

echo "Setting remote origin..."
git remote set-url origin "$REPO_URL"

echo "Pulling latest changes..."
git pull origin main

echo "Fetching Git LFS files..."
git lfs fetch
git lfs pull

# Additional steps added to force proper checkout
git lfs checkout
git lfs pull --include="*"

echo "Deployment complete."

docker-compose.yml配置 #

services:
  webserver:
    container_name: 'myContainer'
    image: nginx:alpine
    restart: always
    networks:
      - proxy
    environment:
      - VIRTUAL_HOST=your.domain.com
      - LETSENCRYPT_HOST=your.domain.com
      - LETSENCRYPT_EMAIL=your@email.com
    volumes:
      - /container/myContainer/static/projects:/usr/share/nginx/html

  github-auto-puller:
    build: /container/myContainer/webhook
    container_name: github-auto-puller
    restart: unless-stopped
    ports:
      - "9870:9000"
    volumes:
      - /container/myContainer/hooks.json:/etc/webhook/hooks.json:ro
      - /container/myContainer/deploy.sh:/scripts/deploy.sh
      - /container/myContainer/static:/data/repo
      - /container/myContainer/ssh:/root/.ssh
    environment:
      - HOME=/root
    command:
      - --hooks
      - /etc/webhook/hooks.json
      - --verbose

networks:
  proxy:
    external: true

1. 检查Git LFS的smudge过滤器配置 #

Git LFS依赖smudge过滤器将指针文件替换为实际内容，若过滤器未启用，拉取后文件仅保留指针。在webhook容器中执行以下命令检查配置：

# 检查全局配置
git config --global filter.lfs.smudge
git config --global filter.lfs.process

# 检查仓库本地配置
cd /data/repo && git config filter.lfs.smudge
cd /data/repo && git config filter.lfs.process

若输出为空或不正确，重新初始化LFS并强制启用过滤器：

cd /data/repo
git lfs install --force
git config filter.lfs.smudge "git-lfs smudge -- %f"
git config filter.lfs.process "git-lfs filter-process"
git config filter.lfs.required true

2. 确认目录权限与文件所有权 #

若webhook容器执行git命令的用户对/data/repo目录无写入权限，LFS无法替换指针为实际内容。检查目录权限：

ls -ld /data/repo
ls -l /data/repo/handfan/Build/handfan.loader.js

确保执行脚本的用户（通常为root）拥有目录读写权限，必要时修改权限：

chown -R root:root /data/repo
chmod -R 755 /data/repo

3. 调整部署脚本的LFS操作顺序 #

当前脚本中git pull后执行冗余的LFS操作，且未确保拉取前LFS配置生效。修改脚本顺序，先确保LFS配置正确，再拉取内容：

#!/bin/bash

REPO_URL="git@github.com:<your-org>/<your-repo>.git"
REPO_DIR="/data/repo"

cd "$REPO_DIR" || exit

echo "Checking Git LFS..."
git lfs version || { echo "Git LFS not installed"; exit 1; }

# 强制初始化LFS过滤器
git lfs install --force
git config filter.lfs.required true

echo "Setting remote origin..."
git remote set-url origin "$REPO_URL"

# 先拉取LFS元数据，再拉取代码
git lfs fetch origin main
git pull origin main

# 强制检查并替换所有LFS文件
git lfs checkout --force

echo "Deployment complete."

4. 确认webhook容器构建时已安装Git LFS #

若webhook容器的Dockerfile未安装Git LFS，手动安装会随容器重启丢失。确保Dockerfile包含以下安装步骤：

• 基于Debian系镜像：

RUN apt-get update && apt-get install -y git git-lfs \
    && git lfs install --system

• 基于Alpine镜像：

RUN apk add --no-cache git git-lfs \
    && git lfs install --system

5. 验证LFS追踪规则 #

进入webhook容器的/data/repo目录，检查LFS追踪规则是否包含目标文件：

cd /data/repo
git lfs track

若handfan/Build/*不在追踪列表中，需在仓库端添加规则并提交，部署端可临时执行以下命令后重新拉取：

cd /data/repo
git lfs track "handfan/Build/*"
git add .gitattributes
git commit -m "Add LFS track rule for handfan build files"
git push origin main

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