Vercelで3DGS (.ply) が表示されない問題を15分で解決
TL;DR
-
Network タブで .ply が 0 kB → ほぼ 100 % Git LFS ポインタしか配信されていない。
-
GitHub で
Stored with Git LFSと出ていたらポインタ確定。 -
対応は 2 択 👇
- Vercel 側で Git LFS を有効にする（ビルドが走るプロジェクトなら Git → Enable LFS を ON）。
-
ポインタを外し実体 32 MB を直接コミット（
git lfs untrack→git rm --cached→git add）。
-
hash 付き Preview URL はログイン必須。公開共有は Production URL を使う。
背景
花の 3D Gaussian Splatting (.ply) を ヒーローセクションに置いた LP を Vercel にデプロイしたら、ローカルで見えている 3D が本番では真っ白＆赤いローディングバーだけ…。
DevTools には Invalid ply header。サイズを見たら 0 kB で配信されていた。
原因を絞り込むまでの 5 分
| チェック | 結果 |
|---|---|
| Network Size | 0 kB / 304 → ファイルが空 |
| GitHub で .ply を開く | Stored with Git LFS 表示 |
git lfs ls-files |
対象 .ply がリストに居る |
→ Git LFS ポインタだけがリポジトリにあり、Vercel ビルドで実体が取れていない と確定。
解決策 A — Vercel で Git LFS を有効化
-
Project → Settings → Git → Git Large File Storage を ON。
-
Redeploy。 -
ビルドログに
> git lfs fetch --all > git lfs checkoutが出れば OK。
注意: static only プロジェクトだと
vercel buildが 0.06 秒で終わり、LFS コマンドが走らない。
package.json に"vercel-build": "git lfs pull"を置くなど「ビルドステップ」を作る必要がある。
解決策 B — ポインタ解除＋実体コミット (今回はこれで突破)
# 1. LFS 追跡を外す
git lfs untrack "scene.compressed-viewer/scene.compressed.ply"
# 2. ポインタをインデックスから外す
git rm --cached scene.compressed-viewer/scene.compressed.ply
# 3. 実体が 32 MB あるか確認
ls -lh scene.compressed-viewer/scene.compressed.ply
# 4. 実体を再追加
git add scene.compressed-viewer/scene.compressed.ply
# 5. コミット & プッシュ
git commit -m "Embed PLY directly (remove LFS)"
git push origin main
GitHub でファイルを開くと Binary file cannot be displayed とだけ出て、Stored with Git LFS が消えれば成功。Vercel が自動デプロイ → Network に 32 MB が載れば 3D 復活！
「ログインしないと見られない?」を解決
-
https://<hash>-project.vercel.appは Preview URL →Protect Preview Deploymentsが ON だと要ログイン。 -
Production エイリアス
https://project.vercel.appを共有すれば誰でも閲覧可能。 - Protect Preview Deployments は Settings → General で OFF にできる。
ついでにやったこと
- 不要になった
sample/と.DS_Storeをgit rm -r。 -
.gitignoreに.DS_Store追加。 - progress bar が気になったので CSS で非表示。
#progressBar {
display: none !important;
}
今後のチューニングメモ
- Draco + glTF or meshopt でさらに軽く。（※これは 3DGS ではなく、従来の 3D メッシュモデル用の圧縮技術です）
- ロード後に
OrbitControls.enableZoom = falseで UX 改善。（3DGS も glTF も共通して使える） -
IntersectionObserverで遅延ロードして LCP を稼ぐ。（複数の 3D モデルがあるページで効果的）
3DGS 特有の最適化メモ
- ply ファイルの品質設定（圧縮率）を調整して容量とクオリティのバランスを探る
- モバイル向けに低解像度版を別途用意することも検討
参考リンク
以上、泣きながら 3D ガウシアンスプラットを LP に載せた日の備忘録でした。
ただ、まだこれでいいのかと不安なところもあるので、（外部サーバーに３ D をおいた方がいいのか？など）。いろいろ試してみます。
Discussion