kotlinOptions 报 unresolved reference，说明 Gradle 未正确加载 Kotlin DSL 支持：需检查 settings.gradle.kts 是否启用 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")，模块级 build.gradle.kts 是否声明 kotlin("jvm") 或 kotlin("android") 插件，且 kotlinOptions 必须置于 android {} 块内；Android 项目还需确保 pluginManagement 包含 google() 和 mavenCentral() 仓库，并匹配 AGP 与 Kotlin 插件版本。
Gradle Kotlin源码（即 build.gradle.kts）里报 Unresolved reference，不是项目代码问题，而是 Gradle 构建脚本自身无法识别 Kotlin DSL 的 API —— 常见于插件未启用、Kotlin DSL 支持缺失、或 IDE 与 Gradle 版本错配。直接改代码没用，得从构建系统层定位。
build.gradle.kts 里 kotlinOptions 报 unresolved reference
这是最典型的信号：当你写 kotlinOptions { jvmTarget = "17" } 却被标红，说明 Gradle 没加载 Kotlin DSL 的编译器配置扩展。
- 检查根目录
settings.gradle.kts是否有enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")（Gradle 8.0+ 必需） - 确认模块级
build.gradle.kts顶部是否声明了 Kotlin 插件：plugins { id("org.jetbrains.kotlin.jvm") version "2.0.0" }（版本必须与当前 Kotlin Gradle Plugin 兼容） - 若用的是 Android 项目，
kotlinOptions必须放在android {}块内，且需先应用com.android.application或com.android.library插件；单独在脚本顶层写会失效 - Gradle 8.4+ 默认禁用
kotlin-dsl的隐式导入，需手动加import org.gradle.kotlin.dsl.*才能用dependencies等函数
plugins { id("...") } 里的字符串 ID 报 unresolved reference
比如 id("com.android.application") 或 id("org.jetbrains.kotlin.android") 标红，本质是 Gradle 无法解析插件坐标 —— 不是拼写错，而是插件仓库或解析机制没就位。
- 检查
settings.gradle.kts中的pluginManagement { repositories { ... } }是否包含google()和mavenCentral()（缺一不可，尤其google()对 Android 插件关键） - Android 项目必须用
com.android.tools.build:gradle（AGP）匹配的 Kotlin 插件版本，例如 AGP 8.7 对应 Kotlin 1.9.20，硬套 Kotlin 2.0.0 会直接让所有插件 ID 失效 - 如果用了
versionCatalogs（libs.versions.toml），确保插件 ID 写法为id(libs.plugins.android.application)，而非字符串字面量 - IDE 缓存常导致插件元数据未加载，执行
./gradlew --stop后重启 AS，并点击File → Reload project from Gradle
依赖声明中 implementation()、api() 报 unresolved reference
implementation("x.y.z") 标红，通常意味着 Gradle Kotlin DSL 的依赖配置函数未被识别，根源在脚本作用域或插件加载顺序。
- 确认
build.gradle.kts里没有漏掉plugins { id("maven-publish") }类插件 —— 某些插件（如publishing）会覆盖默认的dependenciesDSL，导致函数不可见 - 避免在
dependencies块外调用implementation；它只能在dependencies { ... }作用域内使用，写在tasks { ... }或顶层会直接报 unresolved - 多模块项目中，子模块若未声明
plugins { kotlin("jvm") }，其build.gradle.kts就无法使用 Kotlin 相关的依赖函数（如kotlin("stdlib")） - Gradle 8.0+ 移除了
compile等旧配置名，若脚本里混用compile "..."，整个依赖块可能瘫痪，连带implementation都变灰色
自定义函数或 ext 属性在 build.gradle.kts 中不识别
比如你写了 val myVersion: String by extra { "1.0" }，但后续用 myVersion 时标红 —— Kotlin DSL 对 extra 的类型推导比 Groovy 严格得多。
-
ext在 Kotlin DSL 中已弃用，改用extra["key"] = value或更推荐的val myVersion: String by project.extra（需显式声明类型） - 自定义函数必须定义在
build.gradle.kts顶层，且不能嵌套在tasks或configurations块内；否则作用域受限，调用处看不到 - 若函数依赖其他插件提供的类型（如
AndroidComponentsExtension），必须确保该插件已在函数定义前 apply，否则类型擦除导致 unresolved - IDE 对 Kotlin DSL 的语义分析有时滞后，哪怕
./gradlew build成功，AS 仍可能标红；此时优先信任命令行结果，而非编辑器提示
真正卡住人的地方，往往不是语法写错，而是 Gradle 的插件加载时机、Kotlin DSL 的作用域隔离、以及 IDE 缓存对脚本类路径的误判三者叠加。别急着删 .gradle 文件夹，先看 ./gradlew --dry-run 能否列出任务 —— 如果连任务都列不出，问题一定出在 settings.gradle.kts 或插件仓库配置上。
