Flutter リリースビルド時に APIが利用できないときの対応法

Flutterでアプリ開発中、デバッグモードでは正常にAPIを呼び出せるのに、リリースビルドにしたとたんAPIが使えなくなった——そんな経験はないでしょうか。

筆者も個人開発中にこの問題に直面し、原因を調べたところ、Androidの公式ドキュメントにしっかり記載されている内容でした。同じ場面で詰まっている方のために備忘録として残しておきます。

この記事では以下の内容を解説します。

• 発生するエラーの内容と原因
• 具体的な解決方法（コード付き）
• 初学者がドキュメントを読む習慣をつける重要性

発生するエラーと原因

エラー内容

リリースビルド後にAPIリクエストを行うと、以下のようなエラーが発生します。

Error: SocketException: Failed host lookup: 'your-api-endpoint.com'

最最初はAPIのURLが間違っているのかと思い確認しましたが問題なく、デバッグ時は正常に動作していたことから、パーミッション（権限）周りの問題と見当をつけて調べました。

原因：インターネットアクセス権限の設定漏れ

Androidアプリには、インターネットに接続するための権限（Permission）をAndroidManifest.xmlに明示的に記述する必要があります。

ポイントは、デバッグビルドではINTERNET権限が自動的に付与されるのに対し、リリースビルドでは自分で追加しなければならないという点です。このデバッグとリリースの挙動の違いが、この問題が起きやすい原因になっています。

参考

---

解決方法

android/app/src/main/AndroidManifest.xml を開き、<manifest>タグの直下に以下の1行を追加するだけで解決します。

<uses-permission android:name="android.permission.INTERNET"/>

追記後のファイル構成は以下のようになります。

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- この1行を追加 -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <application
        android:label="your_app"
        ...>
        ...
    </application>

</manifest>

この1行を追加した状態でリリースビルドを行うと、問題なくAPIを呼び出せるようになります。

参考

ドキュメントを読む習慣の重要性

この問題の解決策は、公式ドキュメントにしっかりと記載されていました。

初学者の方（筆者もかつてそうでした）は、エラーが出ると「エラー文をそのままコピーして検索→最初に出てきた解説記事のコードをコピーして貼り付け」という対応をしがちです。その場しのぎとしては有効ですが、同じエラーが別の形で起きたときに対処できないというデメリットがあります。

公式ドキュメントを読む習慣をつけることで、以下のメリットがあります。

• 情報の正確性が高い（公式情報なので最も信頼できる）
• バージョンアップへの対応がしやすい
• エラーの「なぜ」が理解でき、応用力がつく
• 英語のドキュメントを読む練習にもなる

ネイティブアプリ開発は特に、端末・OSバージョン・iOSとAndroidの違いによってエラーが多く発生します。調べても解決策が見つからないときは、まず公式ドキュメントに戻ってみることをおすすめします。

まとめ

今回の問題と解決策を一言でまとめると、「Androidのリリースビルドではインターネット権限をAndroidManifest.xmlに手動で追加する必要がある」 ということです。

対応内容は1行追加するだけですが、この原因を知らないとかなり時間を消耗してしまいます。同じ問題で詰まっている方の参考になれば幸いです。

また、エラーに直面したときは、ネット上の解説記事だけでなく公式ドキュメントを読む習慣を日頃から意識しておくと、エンジニアとしての成長スピードが格段に上がります。