3、开发环境准备：Android Studio配置、项目创建、Gradle依赖添加、权限声明

好，咱们正式开始动手了。这一节我会带你一步步把开发环境搭起来。说实话，虹膜识别这块的配置比普通功能要稍微讲究一点，因为涉及到硬件接口和系统权限。我在早期做虹膜项目时，光环境配置就折腾了大半天——嗯，后来发现是漏了一个依赖。

咱们按这个顺序来：先配好Android Studio，再创建项目，然后加Gradle依赖，最后声明权限。每一步我都会把坑指出来。

3.1 Android Studio版本与SDK要求

先说说版本的事。Android Studio建议用最新稳定版，目前是Hedgehog或更高。为什么？因为虹膜识别API在较新的SDK里才完整支持。

3.2 创建项目——选对模板很重要

打开Android Studio，点"New Project"。这里有个小细节：

• 选 Empty Views Activity 或 Empty Compose Activity
• 我个人偏好用Views Activity，因为虹膜识别UI通常需要自定义布局，Compose虽然好但调试起来稍麻烦
• 包名建议用 com.yourcompany.irisapp 这种结构

项目创建好后，第一件事是检查 build.gradle.kts（或 build.gradle）里的SDK版本。我遇到过好几次，默认生成的版本太低，导致后面编译报错。

3.3 Gradle依赖添加——核心就这几个

虹膜识别主要依赖AndroidX的 biometric 库。打开 app/build.gradle.kts，在 dependencies 块里加上：

dependencies {
    // 生物识别核心库
    implementation("androidx.biometric:biometric:1.2.0-alpha05")

    // 如果你用Kotlin协程（我强烈建议）
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")

    // 可选：ViewModel支持
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0")
}

同步一下Gradle。如果网络慢，记得配好国内镜像源。在 settings.gradle.kts 里加：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        google()
        mavenCentral()
    }
}

3.4 权限声明——这一步不能省

虹膜识别需要两个权限：一个是摄像头权限（因为虹膜本质上是通过摄像头采集），另一个是生物识别权限。打开 AndroidManifest.xml，在 <manifest> 标签内添加：

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

<!-- 如果你的应用只针对有虹膜硬件的设备，可以加这个 -->
<uses-feature android:name="android.hardware.iris" android:required="true" />

这里有个容易踩的坑：USE_BIOMETRIC 权限是普通权限，不需要运行时申请。但 CAMERA 是危险权限，必须在运行时动态申请。我早期做项目时忘了这事，结果在Android 10以上的设备上直接崩溃——因为权限被拒绝了。

if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
    != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(
        this,
        arrayOf(Manifest.permission.CAMERA),
        CAMERA_PERMISSION_CODE
    )
} else {
    // 权限已获取，可以初始化虹膜识别
    initIrisAuthentication()
}

3.5 验证环境——跑一个空壳测试

依赖加好了，权限也声明了。怎么确认环境没问题？写一个最简单的Activity，调用 BiometricPrompt 看看能不能弹出对话框。

class MainActivity : AppCompatActivity() {
    private lateinit var biometricPrompt: BiometricPrompt

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val executor = ContextCompat.getMainExecutor(this)
        biometricPrompt = BiometricPrompt(this, executor,
            object : BiometricPrompt.AuthenticationCallback() {
                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                    // 认证成功
                    Log.d("IrisDemo", "认证成功！")
                }

                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                    // 认证出错
                    Log.e("IrisDemo", "错误: $errString")
                }

                override fun onAuthenticationFailed() {
                    // 认证失败
                    Log.w("IrisDemo", "认证失败")
                }
            })

        val promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("虹膜验证")
            .setSubtitle("请看向摄像头")
            .setAllowedAuthenticators(
                BiometricManager.Authenticators.BIOMETRIC_IRIS
            )
            .build()

        findViewById<Button>(R.id.btn_auth).setOnClickListener {
            biometricPrompt.authenticate(promptInfo)
        }
    }
}

3.6 知识体系总览

下面这张图把整个开发环境准备的核心逻辑串起来了。你可以对照着检查自己有没有遗漏：

环境准备这块，说白了就是三板斧：配好SDK、加对依赖、声明权限。只要这三步走对了，后面写代码基本不会因为环境问题卡壳。我个人建议你每加一个依赖就同步一次Gradle，别攒一堆再同步——出错了不好定位。

好了，环境搭好了。下一节咱们就正式进入虹膜识别的核心代码编写。到时候我会把 BiometricPrompt 的每个回调都拆开讲，保证你一看就懂。