Руководство по совместимости для Kotlin 2.4.x

Поддержание актуальности языка и Удобство обновлений — одни из основных принципов проектирования языка Kotlin. Первый гласит, что конструкции, препятствующие развитию языка, следует удалять, а второй — что об этом удалении нужно заблаговременно и ясно сообщать, чтобы упростить миграцию кода.

Хотя большинство изменений языка уже были объявлены в других источниках, например в журналах изменений обновлений или предупреждениях компилятора, в этом документе они собраны вместе, чтобы предоставить полное руководство по переходу с Kotlin 2.3 на Kotlin 2.4. В документе также содержатся сведения об изменениях, связанных с инструментами.

Основные термины

В этом документе рассматриваются несколько видов совместимости:

исходная: изменение, нарушающее исходную совместимость, не позволяет скомпилировать код, который раньше компилировался без ошибок и предупреждений
бинарная: два бинарных артефакта считаются бинарно-совместимыми, если их взаимная замена не приводит к ошибкам загрузки или связывания
поведенческая: изменение считается нарушающим поведенческую совместимость, если одна и та же программа ведет себя по-разному до и после его применения

Обратите внимание, что эти определения применимы только к Kotlin. Совместимость кода Kotlin с точки зрения других языков (например, Java) выходит за рамки этого документа.

Язык

Прекращение поддержки `-language-version=1.9` и компилятора K1

Запретить гибкие явно заданные nullable-аргументы типов для типов Java

Задача: KTLC-284

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Ранее при вызове API Java из Kotlin компилятор мог рассматривать явно заданные nullable-аргументы типов как гибкие аргументы типов. В Kotlin 2.4.0 это поведение больше не применяется к nullable-аргументам типов, поэтому компилятор теперь сообщает об ошибках в коде, который может нарушить безопасность типов или привести к сбою во время выполнения.

Цикл устаревания:

2.2.0: выдавать предупреждение для явно заданных nullable-аргументов типов, которые рассматриваются как гибкие типы
2.4.0: повысить уровень предупреждения до ошибки

Запретить проверки `is`, всегда возвращающие false для заведомо несовместимых типов

Задача: KTLC-365

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь компилятор запрещает бессмысленные проверки is, которые всегда возвращают false, поскольку проверяемые типы заведомо несовместимы. Благодаря этому поведение согласуется с поведением других операций с несовместимыми типами.

Цикл устаревания:

2.0.0: выдавать предупреждение для проверок is с заведомо несовместимыми типами
2.4.0: повысить уровень предупреждения до ошибки

Запретить раскрытие типов и объявлений с более низким уровнем видимости во встроенных функциях

Изменить выбор цели по умолчанию для аннотаций

Задача: KTLC-391

Компонент: Основной язык

Тип несовместимого изменения: бинарная совместимость

Краткое описание: В Kotlin 2.4.0 обновлены правила по умолчанию для распространения аннотаций на параметры, свойства и поля. После повторной компиляции это может повлиять на обработку аннотаций, рефлексию и бинарные метаданные. Если цель применения не указана, компилятор теперь использует param и property, если они применимы, и использует field, только если неприменим property.

Цель применения можно указать явно, например @param:Annotation вместо @Annotation. Чтобы использовать прежнее правило по умолчанию во всём проекте, добавьте -Xannotation-default-target=first-only в файл сборки.

Цикл устаревания:

2.2.0: выдавать предупреждение, если новое правило по умолчанию изменяет выбранные цели применения
2.4.0: включить новое правило по умолчанию

Запретить неявные ссылки на недоступные типы

Задача: KTLC-384

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Использование объявлений, которые неявно ссылаются на недоступные типы из транзитивных зависимостей, теперь приводит к ошибке.

Для перехода добавьте явную зависимость от модуля, в котором объявлен недоступный тип, или обновите промежуточный API, чтобы он не раскрывал этот тип.

Цикл устаревания:

2.3.0: выдавать предупреждение о неявных ссылках на недоступные типы
2.4.0: повысить уровень предупреждения до ошибки

Учитывать аннотации nullable Jakarta

Задача: KTLC-285

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь компилятор учитывает объявленную nullable-семантику в Kotlin для объявлений Java с аннотациями jakarta.annotation.Nullable или jakarta.annotation.Nonnull. Если присвоить объявление Java, помеченное этими аннотациями как nullable, переменной Kotlin с non-null-типом, компилятор сообщит об ошибке.

Цикл устаревания:

2.2.0: выдавать предупреждение о несоответствии nullable-семантики в объявлениях Java с аннотациями nullable Jakarta
2.4.0: повысить уровень предупреждения до ошибки

Сообщать о неправильно расположенных аргументах типов в квалификаторах ссылок на вызываемые элементы

Задача: KTLC-388

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь компилятор проверяет левую часть ссылок на вызываемые элементы и выдаёт предупреждение, если во внутреннем классе аргументы типов указаны не в той части квалификатора.

Для перехода измените ссылку так, чтобы каждый аргумент типа относился к классу, в котором он объявлен. Например, укажите полный тип Outer<Int>.Inner<String>::toString вместо Inner<String, Int>::toString.

Цикл устаревания:

2.4.0: выдавать предупреждение, если аргументы типов в левой части ссылки на вызываемый элемент относятся к другой части квалификатора

Сообщать об ошибках для литералов классов, полученных из reified-параметров типов с nullable-верхними границами

Задача: KTLC-370

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь компилятор сообщает об ошибке при использовании ::class для выражения, тип которого получен из reified-параметра типа с nullable-верхней границей. Если для такого выражения используется ::class, сначала сделайте значение non-null с помощью явной проверки на null или оператора !!.

Цикл устаревания:

2.3.0: выдавать предупреждение при использовании ::class для выражения, тип которого получен из reified-параметра типа с nullable-верхней границей
2.4.0: повысить уровень предупреждения до ошибки

Запретить инициализацию до объявления свойств в анонимных объектах

Требовать полноты выражений `when` с неабстрактными запечатанными классами Java

Задача: KTLC-366

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь Kotlin строже проверяет полноту и требует ветвь else или ветвь, соответствующую самому запечатанному классу, если в выражении when используется неабстрактный запечатанный класс Java. Ранее Kotlin мог считать такие выражения when полными, хотя сам запечатанный класс Java можно было инстанцировать напрямую.

Цикл устаревания:

2.3.0: выдавать предупреждение для неполных выражений when с неабстрактными запечатанными классами Java
2.4.0: повысить уровень предупреждения до ошибки

Запретить модификатор `operator` для функций `getValue()` и `setValue()` с избыточным числом параметров

Задача: KTLC-289

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Если пометить функции getValue() или setValue() модификатором operator, компилятор теперь проверяет, что у них необходимое количество параметров-значений. Функция getValue() должна иметь ровно два параметра-значения, а функция setValue() — ровно три. Чтобы перейти на новую версию, удалите модификатор operator или измените сигнатуру функции.

Цикл устаревания:

2.2.20: выдавать предупреждение для функций operator getValue() и setValue() с избыточным количеством параметров-значений
2.4.0: повысить уровень предупреждения до ошибки

Запретить несогласованные аргументы типов в вызовах обобщённых функций

Задача: KTLC-373

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Если при вызове обобщённой функции указать аргументы типов, компилятор теперь сообщает об ошибке, если один из аргументов типов нарушает ограничение верхней границы, зависящее от другого аргумента типа. Если параметры типов зависят друг от друга, укажите аргументы типов, соответствующие этим ограничениям, например Container<Alpha, AlphaKey>() вместо Container<Alpha, BetaKey>().

Цикл устаревания:

2.3.0: выдавать предупреждение, если явно указанные аргументы типов в вызове обобщённой функции нарушают ограничения верхних границ между параметрами типов
2.4.0: повысить уровень предупреждения до ошибки

Устаревание ссылок на свойство `javaClass`

Сообщать об ошибках при неявных вызовах конструктора enum, требующих opt-in

Задача: KTLC-359

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь Kotlin сообщает об ошибке, если элемент enum неявно вызывает первичный конструктор enum, требующий opt-in. Чтобы перейти на новую версию, добавьте @OptIn к классу enum или к каждому элементу enum, вызывающему этот конструктор.

Цикл устаревания:

2.2.20: выдавать предупреждение, если элемент enum неявно вызывает первичный конструктор enum, требующий opt-in
2.4.0: повысить уровень предупреждения до ошибки

Запретить модификатор `inline` для элементов enum

Запретить литералы массивов вне вызовов аннотаций и значений параметров по умолчанию

Задача: KTLC-369

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Использование литералов массивов вне вызовов аннотаций и значений по умолчанию для параметров аннотаций теперь приводит к ошибке. Чтобы перейти на новую версию, используйте arrayOf(...), например Roles(arrayOf("admin", "user")) вместо Roles(["admin", "user"]).

Цикл устаревания:

2.3.0: выдавать предупреждение для литералов массивов вне вызовов аннотаций и значений по умолчанию для параметров аннотаций
2.4.0: повысить уровень предупреждения до ошибки

Запретить `_root_ide_package_` в режиме CLI-компилятора

Исправить сравнение на равенство ссылок на функции с преобразованиями vararg

Задача: KTLC-385

Компонент: Kotlin/JVM

Тип несовместимого изменения: поведенческое

Краткое описание: Теперь Kotlin/JVM считает ссылки на функции с разными преобразованиями неравными. Ранее Kotlin/JVM игнорировал преобразование vararg при проверке на равенство, если та же ссылка на функцию также использовала другое преобразование, поэтому getDefault(::foo) == getDefaultAndVararg(::foo) могло вернуть true, даже если преобразование vararg использовалось только с одной стороны.

Цикл устаревания:

2.4.0: ввести новое поведение

Требовать opt-in для доступа к объекту-компаньону

Задача: KTLC-386

Компонент: Основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь Kotlin сообщает об ошибке opt-in, если ссылка на имя класса разрешается в объект-компаньон, требующий opt-in. Например, для val p = C требуется opt-in, если C разрешается в объект-компаньон, помеченный аннотацией opt-in.

Цикл устаревания:

2.3.20: выдавать предупреждение, если для доступа к объекту-компаньону требуется opt-in
2.4.0: повышать уровень предупреждения до ошибки для требований opt-in на уровне ERROR

Сообщать о несоответствиях типов в супертипах со вложенными обобщёнными аргументами

Проблема: KTLC-372

Компонент: основной язык

Тип несовместимого изменения: исходный код

Краткое описание: Теперь Kotlin сообщает об ошибке, если компилятор обнаруживает несоответствие типов, связанное с супертипом со вложенными обобщёнными аргументами. Ранее компилятор мог пропустить это несоответствие, что впоследствии приводило к сбою с ClassCastException. Для миграции используйте аргумент типа, соответствующий обобщённому типу получателя, или удалите явный аргумент типа, чтобы компилятор мог вывести его.

Цикл устаревания:

2.4.0: сообщать об ошибке при несоответствии типов, связанном с супертипами со вложенными обобщёнными аргументами

Запретить выведенные типы с недоступными объявлениями

Стандартная библиотека

Объявить функцию `kotlin.io.readLine()` устаревшей

Объявить `AbstractCoroutineContextKey` и связанные API устаревшими

Изменить контракт `Random.nextDouble()` для бесконечных границ

Инструменты

Объявить устаревшими API выбора типа устаревшего компилятора Kotlin/JS

Проблема: KT-64275, KT-84753

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: В Kotlin 2.4.0 удаляются устаревшие API Gradle, связанные с выбором типа устаревшего компилятора Kotlin/JS.

Кроме того, перечисление KotlinJsCompilerType и перегрузки KotlinProjectExtension.js() с параметром типа компилятора объявляются устаревшими. Для миграции удалите аргумент типа компилятора из объявления цели js() и используйте вместо него блок js {}.

Цикл устаревания:

1.8.0: объявить устаревшими константы типа устаревшего компилятора Kotlin/JS
2.4.0: удалить устаревшие API типа устаревшего компилятора и выдавать предупреждение при использовании KotlinJsCompilerType или перегрузок KotlinProjectExtension.js() с параметром типа компилятора

Объявить `sourceSets` устаревшим в расширении Kotlin Android

Удалить потребляемые конфигурации для фреймворков Apple в Kotlin/Native

Удалить устаревшие API задач, компиляции и DSL из плагина Kotlin Gradle

Проблема: KT-85509

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: В Kotlin 2.4.0 удаляются следующие устаревшие API плагина Kotlin Gradle:

API настройки задач компиляции:

KotlinJvmCompile.parentKotlinOptions
KotlinJvmCompile.moduleName
KotlinJvmFactory.createKotlinJvmOptions()
BaseKotlinCompile.moduleName из задач KotlinCompile и Kotlin2JsCompile

API иерархии и целей Kotlin Multiplatform:

DeprecatedKotlinTargetHierarchyDsl
KotlinMultiplatformExtension.targetHierarchy
KotlinTargetComponent.sourcesArtifacts
KotlinTarget.sourceSets
KotlinHierarchyBuilder.withoutCompilations()
KotlinHierarchyBuilder.filterCompilations()
KotlinHierarchyBuilder.withWasm()
KotlinCompilation.defaultSourceSetName

API задач компиляции Kotlin:

KotlinCompilation.compileKotlinTaskProvider
KotlinCompilation.compileKotlinTask

API обработчика зависимостей Kotlin:

KotlinDependencyHandler.enforcedPlatform()
KotlinDependencyHandler.platform() Другие устаревшие API задач и расширений:
KaptExtension.processors
KotlinTest.excludes
KotlinTest.fileResolver
KotlinTest.execHandleFactory
IncrementalSyncTask.destinationDir

Для миграции удалите использования этих API и воспользуйтесь заменами, предлагаемыми диагностическими сообщениями об устаревании.

Цикл устаревания:

2.4.0: удалить устаревшие API

Объявить устаревшей явную настройку уменьшенного снимка classpath

Проблема: KT-75837

Компонент: API средств сборки

Тип несовместимого изменения: исходный код

Краткое описание: Параметр конфигурации shrunkClasspathSnapshot в ClasspathSnapshotBasedIncrementalCompilationApproachParameters объявлен устаревшим. Уменьшенный снимок classpath — это внутренний кеш инкрементальной компиляции, поэтому теперь компилятор автоматически создаёт его и управляет им в каталоге метаданных инкрементального компилятора workingDirectory. Для миграции используйте файл снимка, управляемый автоматически, вместо передачи значения в shrunkClasspathSnapshot.

Цикл устаревания:

2.4.0: выдавать предупреждение при использовании shrunkClasspathSnapshot

Удалить избыточные элементы DSL Gradle для проверки ABI

Объявить устаревшими устаревшие параметры плагина Compose Compiler для Gradle

Проблема: KT-85343

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: В Kotlin 2.4.0 при использовании следующих устаревших параметров плагина Compose Compiler для Gradle теперь сообщается об ошибке:

generateFunctionKeyMetaClasses
enableIntrinsicRemember
enableNonSkippingGroupOptimization
enableStrongSkippingMode
stabilityConfigurationFile
ComposeFeatureFlag.StrongSkipping
ComposeFeatureFlag.IntrinsicRemember

Используйте featureFlags вместо устаревших параметров функций, а stabilityConfigurationFiles — вместо stabilityConfigurationFile.

Цикл устаревания:

2.0.20: выдавать предупреждения для enableIntrinsicRemember, enableNonSkippingGroupOptimization и enableStrongSkippingMode
2.1.0: выдавать предупреждение для stabilityConfigurationFile
2.4.0: повысить уровень предупреждений до ошибок

Сообщать об ошибках при использовании устаревших API задач Gradle для Kotlin/Native

Проблема: KT-85510

Компонент: Gradle

Тип несовместимого изменения: исходный код

Краткое описание: При использовании следующих устаревших API задач Gradle для Kotlin/Native теперь сообщается об ошибке:

Свойства AbstractKotlinNativeCompile:

additionalCompilerOptions
languageSettings
progressiveMode

Свойства KotlinNativeCompile:

moduleName
konanDataDir
konanHome
languageVersion
apiVersion
enabledLanguageFeatures
optInAnnotationsInUse
additionalCompilerOptions

Свойства CInteropProcess:

outputFile
konanDataDir
konanHome
defFile

Свойства KotlinNativeLink:

languageSettings
additionalCompilerOptions
konanDataDir
konanHome

Кроме того, свойство KotlinNativeLink.compilation удаляется.

Цикл устаревания:

2.4.0: сообщать об ошибке для устаревших API задач Gradle для Kotlin/Native и удалить свойство KotlinNativeLink.compilation

Выдавать предупреждения при несовпадении регистра в значениях аргументов компилятора

Проблема: KT-86059

Компонент: API средств сборки

Тип несовместимого изменения: исходный код

Краткое описание: Ранее аргументы компилятора, принимающие фиксированный набор значений, обрабатывали регистр букв непоследовательно: одни принимали любой регистр, а другие требовали точного совпадения. Теперь API средств сборки принимает значения в любом регистре, но выдаёт предупреждение, например Case mismatch for -module-kind: expected 'commonjs', got 'CommonJS'. Для миграции используйте регистр, указанный для аргумента в справочнике по компилятору.

Цикл устаревания:

2.4.20: выдавать предупреждение, если регистр значения аргумента компилятора не соответствует ожидаемому

24 августа 2026 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/compatibility-guide-24.html

Руководство по совместимости для Kotlin 2.4.x

Основные термины

Язык

Прекращение поддержки -language-version=1.9 и компилятора K1

Запретить гибкие явно заданные nullable-аргументы типов для типов Java

Запретить проверки is, всегда возвращающие false для заведомо несовместимых типов

Запретить раскрытие типов и объявлений с более низким уровнем видимости во встроенных функциях

Изменить выбор цели по умолчанию для аннотаций

Запретить неявные ссылки на недоступные типы

Учитывать аннотации nullable Jakarta

Сообщать о неправильно расположенных аргументах типов в квалификаторах ссылок на вызываемые элементы

Сообщать об ошибках для литералов классов, полученных из reified-параметров типов с nullable-верхними границами

Запретить инициализацию до объявления свойств в анонимных объектах

Требовать полноты выражений when с неабстрактными запечатанными классами Java

Запретить модификатор operator для функций getValue() и setValue() с избыточным числом параметров

Запретить несогласованные аргументы типов в вызовах обобщённых функций

Устаревание ссылок на свойство javaClass

Сообщать об ошибках при неявных вызовах конструктора enum, требующих opt-in

Запретить модификатор inline для элементов enum

Запретить литералы массивов вне вызовов аннотаций и значений параметров по умолчанию

Запретить _root_ide_package_ в режиме CLI-компилятора

Исправить сравнение на равенство ссылок на функции с преобразованиями vararg

Требовать opt-in для доступа к объекту-компаньону

Сообщать о несоответствиях типов в супертипах со вложенными обобщёнными аргументами

Запретить выведенные типы с недоступными объявлениями

Стандартная библиотека

Объявить функцию kotlin.io.readLine() устаревшей

Объявить AbstractCoroutineContextKey и связанные API устаревшими

Изменить контракт Random.nextDouble() для бесконечных границ

Инструменты

Объявить устаревшими API выбора типа устаревшего компилятора Kotlin/JS

Объявить sourceSets устаревшим в расширении Kotlin Android

Удалить потребляемые конфигурации для фреймворков Apple в Kotlin/Native

Удалить устаревшие API задач, компиляции и DSL из плагина Kotlin Gradle

Объявить устаревшей явную настройку уменьшенного снимка classpath

Удалить избыточные элементы DSL Gradle для проверки ABI

Объявить устаревшими устаревшие параметры плагина Compose Compiler для Gradle

Сообщать об ошибках при использовании устаревших API задач Gradle для Kotlin/Native

Выдавать предупреждения при несовпадении регистра в значениях аргументов компилятора

Прекращение поддержки `-language-version=1.9` и компилятора K1

Запретить проверки `is`, всегда возвращающие false для заведомо несовместимых типов

Требовать полноты выражений `when` с неабстрактными запечатанными классами Java

Запретить модификатор `operator` для функций `getValue()` и `setValue()` с избыточным числом параметров

Устаревание ссылок на свойство `javaClass`

Запретить модификатор `inline` для элементов enum

Запретить `_root_ide_package_` в режиме CLI-компилятора

Объявить функцию `kotlin.io.readLine()` устаревшей

Объявить `AbstractCoroutineContextKey` и связанные API устаревшими

Изменить контракт `Random.nextDouble()` для бесконечных границ

Объявить `sourceSets` устаревшим в расширении Kotlin Android