Firebase Functions (Python) で起動時エラーが出る原因と対策

Firebase Functions (Python) で起動時エラーが出る原因と対策

Firebase Functions (Python) で起動時エラーが出る原因と対策

よくあるエラーの正体

Firebase Functions を Python で書いていると、起動時に次のようなエラーが出ることがあります。

functions: Failed to load function definition from source: FirebaseError: Functions codebase could not be analyzed successfully.

これは「コードの静的解析段階でコケている」状態で、構文エラーや import 時の副作用、存在しないモジュール呼び出しなどが原因になります。

読者

「import しただけで落ちるのはどうして？」

原因の多くはトップレベルの import や初期化処理です。

特に firebase_admin.initialize_app() を main.py の先頭で実行していたり、サービスアカウント JSON を相対パスで読み込んでいたりすると、Firebase CLI が解析時に例外を投げてしまいます。

ごりら

「initialize_app は専用の util にまとめて、必要なときにだけ呼ぶのが安全だよ」

遅延 import と初期化の徹底

起動時に落ちないようにするには、コントローラやサービスの import を各関数の中に移動します。

また、Firebase Admin SDK の初期化は util モジュールを作り、ensure_app() のように一度だけ呼ばれる関数にまとめておくのが推奨です。

読者

「トップでまとめて import するのはダメなの？」

ダメではないですが、循環 import や副作用で解析が失敗しやすくなります。

特に Python の場合は import 時にコードが即実行されるため、トップに重い処理を書くとデプロイすらできなくなります。

ごりら

「関数の中で import すれば、リクエスト時に初めてロードされるから安全だね」

サンプル: main.py

from firebase_functions import https_fn

@https_fn.on_request()
def getUser(req: https_fn.Request):
    from utils.auth_utils import require_auth
    from controllers import user_controller

    @require_auth
    def _inner(request: https_fn.Request):
        return user_controller.get_user_controller(request)

    return _inner(req)

サンプル: utils/admin_app.py

import os
import firebase_admin
from firebase_admin import credentials

def ensure_app():
    if not firebase_admin._apps:
        try:
            firebase_admin.initialize_app()  # ADC を使用
        except Exception:
            cred_path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
            if not cred_path:
                raise
            cred = credentials.Certificate(cred_path)
            firebase_admin.initialize_app(cred)
    return firebase_admin.get_app()

firebase.json の例

{
  "functions": {
    "source": "functions",
    "runtime": "python311"
  }
}

未定義メソッド呼び出しが検出されない理由

今回のケースでは review_controller 内で存在しないメソッドを呼んでいたことも原因でした。

Python は動的型付け言語なので、コンパイル時に未定義メソッドをチェックしません。実際にそのコードパスを実行して初めて AttributeError が発生します。

読者

「なんでコンパイルエラーにならないの？」

Python は「実行して初めてエラーになる」仕様だからです。静的解析をしてくれるのは mypy や pyright のような外部ツールだけです。

ごりら

「mypy を CI に入れておけば、未定義メソッドも事前に検出できるよ」

pyproject.toml (mypy 設定例)

[tool.mypy]
python_version = "3.11"
strict = true
warn_unused_configs = true
warn_return_any = true
disallow_untyped_defs = true
no_implicit_optional = true

pytest を使ったスモークテスト

未定義メソッドや import エラーを早期に検出するには、pytest を用いた簡単なスモークテストが有効です。

tests/test_reviews.py

from controllers import review_controller

class DummyRequest:
    method = "POST"
    def get_json(self, silent=True):
        return {"rating": 5, "comment": "great", "userName": "Taro"}

def test_submit_review_smoke():
    req = DummyRequest()
    res = review_controller.submit_review_controller(req)
    assert res.status == 200

CI/CD パイプラインにこのテストを組み込めば、本番デプロイ前にバグを防げます。