はじめに
個人開発で Astro (Frontend) + Python FastAPI (Backend) の構成を Vercel にデプロイして運用しています。 開発の過程で発生した「プロジェクト誤削除インシデント」と、その後のリカバリ、および発生したビルドエラーの技術的な解消手順を共有します。
特に Vercel Postgres (Neon) を使用している場合のプロジェクト復旧や、最近の Python Runtime (uv) 更新に伴うエラーなどは、同様のスタックで開発されている方の参考になるかと思います。
技術スタック
Frontend: Astro 5, React, Tailwind CSS
Backend: Python 3.12, FastAPI (Serverless Functions)
Database: Vercel Postgres (Neon)
CMS: microCMS
Deployment: Vercel (Monorepo)
💥 インシデント1: Vercelプロジェクトの誤削除
管理画面での操作ミスにより、本番運用中のVercelプロジェクトを削除してしまう事象が発生。 データベース（Postgres）内のお客様データの消失が危惧されました。
✅ 技術的解説と復旧
Vercelのアーキテクチャにおいて、Project（アプリケーション層） と Storage（データ永続化層） は疎結合になっています。 プロジェクトを削除しても、プロビジョニングされた Database インスタンス自体は独立して残存しています。
復旧フロー:
Re-Import: Vercel Dashboard から GitHub リポジトリ (kazesift/market-sift) を再度インポート。
Env Config: PUBLIC_MICROCMS_SERVICE_DOMAIN 等の環境変数を再設定。
Link Database: ここが重要です。新規作成ではなく、Connect Store から既存の neon-violet-... 等のデータベースを選択してリンク。
これにより、データ損失なくアプリケーションとの接続のみを修復することに成功しました。
🛠️ インシデント2: ビルドパイプラインの連続失敗
プロジェクト復旧後の初回デプロイにおいて、複数の要因によるビルドエラーが発生。 一つずつスタックトレースを解析し解決しました。
- Python Build Error (uv hardlink issue)
Error: warning: Failed to hardlink files; falling back to full copy.
原因: VercelのPythonビルドで使用されているパッケージマネージャー uv が、ファイルシステムの制約によりハードリンク作成に失敗している警告が出ていました。これがビルドプロセスに悪影響を与えていました。
Solution: 環境変数 UV_LINK_MODE を copy に設定することで、ハードリンクではなくコピーを使用するように強制し、安定化させました。
UV_LINK_MODE=copy
- TypeScript Compilation Error (Interface Mismatch)
Error: Type '"etf"' is not assignable to type 'Category'. 原因: CMS側に新しいカテゴリ（ETF, Finance等）を追加した際、Frontendの型定義 (
types.ts) の更新が漏れていました。 ローカル開発環境（Dev Server）では許容されていたものの、Vercelのビルドプロセス（tsc / astro check）での厳格な型チェックにより発覚しました。
Solution:
Signal
インターフェースの Union Type を更新。
// src/types.ts
export interface Signal {
// ...
category: "tourism" | "retail" | ... | "technology" | "finance" | "etf" | "other";
}
- Module Not Found (Git Untracked Files)
Error: Module not found: Can't resolve '@/lib/microcms' 原因: ローカルで実装した
src/lib/microcms.ts
が、
.gitignore
に含まれていないにも関わらず、Git のステージングに追加されていませんでした。 ローカルではファイルが存在するため動作しますが、CI/CD環境（Vercel）にはファイルが転送されず、インポートエラーとなっていました。
Solution: 基本中の基本ですが、git status でUntracked fileを確認し、コミット。
git add src/lib/microcms.ts
git commit -m "feat: add microcms client"
- Logic Duplication (Code Regression)
事象: 修正時のコンフリクト解消ミス（あるいはコピペミス）により、
MarketDashboard.tsx
内のフィルターロジックが2重に定義される事態が発生。 構文エラーにはなりませんでしたが、可読性が著しく低下し、予期せぬ挙動のリスクがありました。
Solution: 重複コードを削除し、フィルタリングロジックを単一のブロックに統合してリファクタリング。
まとめ
今回のトラブルシューティングから得られた知見です。
VercelのStorageはプロジェクトから独立している: 誤ってプロジェクトを消しても、慌てずに再連携すればデータは戻る。
CI環境とローカル環境の差異: git status の確認不足や、ビルドツールの挙動の違い（uv）は、ローカルでは気づきにくい。
型定義の同期: CMSなどの外部スキーマを変更したら、即座にFrontendの型定義も更新するフローを徹底する。
開発における「冷や汗」体験の共有でした。同じエラーに遭遇した方の助けになれば幸いです。
Created by Market Sift Dev Team