在 Flutter 中用 Firebase Auth 实现手机号码验证

📅

loading..🐩🐩🐩🐩

开始之前 🔗

本文基于 firebase_auth ^5.5.0 编写。

下文假设你已在 Firebase 控制台↗创建项目并注册应用。如果还没注册，请参阅注册应用。

Naver Cloud Console、Kakao AlimTalk 和 NICE 认证等服务都支持手机验证。本文使用在 Flutter 中较容易集成的

Firebase Auth

，演示如何实现手机号码验证。

1. 配置 Firebase Auth 🔗

在 Firebase 控制台打开“构建 → Authentication”，点击开始使用。

开始使用 Authentication

在随后出现的登录方式设置中启用“电话”。如果使用模拟器，请添加一个测试电话号码及相应验证码。

我添加的是 +1 1234567812 和 123654。

启用电话登录

电话登录已启用

2. 添加 SHA 证书指纹（Android） 🔗

2.1. 获取证书指纹 🔗

要在 Android 应用中使用 Firebase 身份验证，需要添加 SHA 证书指纹。可以用以下命令查看。

系统提示输入密码时，输入默认密码 android。

MAC/Linux

keytool -list -v \
-alias androiddebugkey -keystore ~/.android/debug.keystore

Windows

keytool -list -v \
-alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

执行成功后会显示如下内容。

查找 SHA 证书指纹

2.2. 添加 SHA 证书指纹 🔗

在 Firebase 控制台中打开已注册的 Android 应用设置。

Android 应用设置

在“常规”标签页下的“我的应用”区域，点击添加指纹。

添加证书指纹

分别添加 SHA1 和 SHA256 证书指纹。

3. 编写 Flutter 代码 🔗

我的目录结构如下。main.dart 会调用 page_onboarding.dart。

📦lib
┣ 📜main.dart
┣ 📜page_onboarding.dart

3.1. 添加 Firebase Auth 插件 🔗

在项目根目录运行以下命令，添加插件。

flutter pub add firebase_auth

3.2. 编写 page_onboarding.dart 🔗

在 page_onboarding.dart 中添加下面的代码。电话号码使用上面添加的测试号码。

/lib/page_onboarding.dart

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';
 
class PageOnboarding extends StatelessWidget {
  const PageOnboarding({super.key});
 
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextButton(
                onPressed: () async {
                  await FirebaseAuth.instance.verifyPhoneNumber(
                    phoneNumber: '+1 1234567812', // 테스트 번호
                    verificationCompleted: (PhoneAuthCredential credential) {
                      print("credential: $credential");
                    },
                    verificationFailed: (FirebaseAuthException e) {
                      print("verificationFailed: $e");
                    },
                    codeSent: (String verificationId, int? resendToken) {
                      print("codeSent: $verificationId");
                      print("codeSent: $resendToken");
                    },
                    codeAutoRetrievalTimeout: (String verificationId) {
                      print("codeAutoRetrievalTimeout: $verificationId");
                    },
                  );
                },
                child: const Text("Phone Number Verification"))
          ],
        ),
      ),
    );
  }
}

点击文字，完成验证码挑战，然后确认日志是否显示验证完成。

如果遇到下面的错误，请参阅请求验证时发生错误。

Fatal error: Please register custom URL scheme app-1-****** in the app's Info.plist file.

4. 了解 verifyPhoneNumber 函数的回调 🔗

4.1. verificationCompleted 🔗

这是自动处理短信验证码的回调，仅在 Android 设备上生效。

verificationCompleted: (PhoneAuthCredential credential) {
  print("credential: $credential");
	await auth.signInWithCredential(credential); // 자동 인증 과정 진행
},

4.2. verificationFailed 🔗

处理失败事件，例如电话号码无效或超出短信配额。

verificationFailed: (FirebaseAuthException e) {
	if (e.code == 'invalid-phone-number') {
		print('The provided phone number is not valid.');
	} else {
		print("verificationFailed: $e");
	}
},

4.3. codeSent 🔗

Firebase 向设备发送验证码后会调用此回调，可以用它提示用户输入验证码。

codeSent: (String verificationId, int? resendToken) {
  print("codeSent: $verificationId");
  print("codeSent: $resendToken");
},

4.4. codeAutoRetrievalTimeout 🔗

无法自动读取短信验证码时，通过此回调处理超时。

codeAutoRetrievalTimeout: (String verificationId) {
  print("codeAutoRetrievalTimeout: $verificationId");
},

5. 处理验证完成 🔗

用户输入短信验证码后，可以用以下代码完成验证。

verificationId 使用 4.3. codeSent 中收到的值，详见完整代码。

/lib/page_onboarding.dart

TextButton(
	onPressed: () async {
		PhoneAuthCredential credential =
				PhoneAuthProvider.credential(
						verificationId: verificationId,
						smsCode: "123654",
						);
		await FirebaseAuth.instance
				.signInWithCredential(credential)
				.then((value) {
				print("signInWithCredential: $value");
		}).catchError((error) {
			print("signInWithCredential: $error");
		});
	},
	child: const Text("Sign In"),
),

常见问题与解决方法 🔗

构建错误：CocoaPods 版本冲突 🔗

Firebase/CoreOnly (= 11.8.0)
2
 
    You have either:
     * out-of-date source repos which you can update with pod repo update or with pod install --repo-update.
     * changed the constraints of dependency Firebase/CoreOnly inside your development pod firebase_core.
       You should run pod update Firebase/CoreOnly to apply changes you've made.
 
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:317:in raise_error_unless_state'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:299:in block in unwind_for_conflict'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:297:in tap'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:297:in unwind_for_conflict'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:257:in process_topmost_state'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:182:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolver.rb:43:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/resolver.rb:94:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:1082:in block in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/user_interface.rb:64:in section'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:1080:in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:125:in analyze'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:422:in analyze'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:244:in block in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/user_interface.rb:64:in section'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:243:in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:162:in install!'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/command/install.rb:52:in run'
    /Library/Ruby/Gems/2.6.0/gems/claide-1.1.0/lib/claide/command.rb:334:in run'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/command.rb:52:in run'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/bin/pod:55:in <top (required)>'
    /usr/local/bin/pod:23:in load'
    /usr/local/bin/pod:23:in `<main>'
 
Error output from CocoaPods:
↳
 
    [!] Automatically assigning platform iOS with version 13.0 on target Runner because no platform was specified. Please specify a platform for this target in your Podfile. See https://guides.cocoapods.org/syntax/podfile.html#platform.
 
Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies.
To update the CocoaPods specs, run:
  pod repo update
 
Error running pod install
Error launching application on iPhone 16 Pro Max.

解决方法 🔗

CocoaPods 的仓库可能已经过时。更新仓库后重新安装依赖。

pod repo update
pod install --repo-update

构建错误：Firebase 版本冲突 🔗

Podfile.lock 将 Firebase/CoreOnly 锁定在 11.6.0，但 firebase_core 插件要求 11.8.0，因而发生版本冲突。

!] CocoaPods could not find compatible versions for pod "Firebase/CoreOnly":
  In snapshot (Podfile.lock):
    Firebase/CoreOnly (= 11.6.0)
 
  In Podfile:
    firebase_core (from .symlinks/plugins/firebase_core/ios) was resolved to 3.12.0, which depends on
      Firebase/CoreOnly (= 11.8.0)
 
You have either:
 * changed the constraints of dependency Firebase/CoreOnly inside your development pod firebase_core.
   You should run pod update Firebase/CoreOnly to apply changes you've made.

解决方法 🔗

删除 Podfile.lock，再重新安装依赖。

rm ios/Podfile.lock
pod install --repo-update

请求验证时发生错误 🔗

在 iOS 上，应用为了进行 reCAPTCHA 验证会打开浏览器。如果没有注册 URL Scheme，从浏览器返回应用时可能会出现以下错误。

Fatal error: Please register custom URL scheme app-1-****** in the app's Info.plist file.

解决方法 🔗

按下面的方式在 info.plist 中添加 URL Scheme。

/ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>app-1-******</string>
        </array>
    </dict>
</array>

结语 🔗

完整代码 🔗

展开查看

/lib/page_onboarding.dart

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
 
class PageOnboarding extends StatefulWidget {
  const PageOnboarding({super.key});
 
  @override
  State<PageOnboarding> createState() => _PageOnboardingState();
}
 
class _PageOnboardingState extends State<PageOnboarding> {
  String verificationId = '';
 
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextButton(
              onPressed: () async {
                await FirebaseAuth.instance.verifyPhoneNumber(
                  phoneNumber: '+1 1234567812', // 테스트 번호
                  timeout: const Duration(seconds: 60),
                  verificationCompleted: (PhoneAuthCredential credential) {
										print("verificationCompleted: $credential");
                  },
                  verificationFailed: (FirebaseAuthException e) {
										print("verificationFailed: $e");
                  },
                  codeSent: (String verificationId, int? resendToken) {
                    this.verificationId = verificationId;
										print("codeSent: $verificationId");
										print("codeSent: $resendToken");
                  },
                  codeAutoRetrievalTimeout: (String verificationId) {
										print("codeAutoRetrievalTimeout: $verificationId");
                  },
                );
              },
              child: const Text("Phone Number Verification"),
            ),
            const SizedBox(height: 20),
            SizedBox(
              width: 200,
              child: TextField( 	// 인증 코드 입력 (123654)
                onChanged: (value) {
                  setState(() {
                    smsCode = value;
                  });
                },
              ),
            ),
            TextButton(
              onPressed: () async {
                PhoneAuthCredential credential = PhoneAuthProvider.credential(
                    verificationId: verificationId, smsCode: smsCode);
                await FirebaseAuth.instance
                    .signInWithCredential(credential)
											.then((value) {
										print("signInWithCredential: $value");
                }).catchError((error) {
										print("signInWithCredential: $error");
                });
              },
              child: const Text("Sign In"),
            ),
          ],
        ),
      ),
    );
  }
}

进一步思考 🔗

试着单独做一个输入短信验证码的页面。
可以让用户知道验证码是否已经发送、还剩多少时间吗？
有没有办法去掉 reCAPTCHA？

参考资料 🔗

在 Flutter 中用 Firebase Auth 实现手机号码验证 | PromleeBlog