Nuxt 4.6: что меняет отдельный API серверного кода

Nuxt 4.6 предлагает отдельный публичный интерфейс nuxt/server для серверных обработчиков и утилит. Он уменьшает прямую связь такого кода с внутренними API h3 и Nitro, но не делает автоматически переносимым всё приложение. Проверять нужно границу конкретного обработчика, его зависимости и состав инструментов выпуска.

Новый интерфейс не означает отказ от Nitro

Официальный выпуск Nuxt 4.6 представляет nuxt/server как импортируемую поверхность серверного кода. Nitro остаётся реализацией по умолчанию; @nuxt/vite-server назван экспериментальным вариантом. Поэтому новость не требует немедленно менять движок проекта или объявлять эксперимент обычным производственным путём.

В том же обновлении поставляется Nuxt CLI 4. У CLI и ядра нужно отдельно читать требования к окружению. Страница ядра 4.6 указывает Node.js ^22.22.3, ^24.15.0 либо версии от 26.0.0; более низкий порог на странице CLI не заменяет требований самой используемой версии Nuxt.

Проследите один обработчик от запроса до ответа

Возьмём вымышленный обработчик состояния заявки. Он читает идентификатор, проверяет доступ, получает данные и возвращает ответ. Смена источника импорта серверной утилиты относится лишь к части этого пути. Она не переписывает запрос к базе и не решает, какой пользователь имеет право видеть заявку.

Это наш разбор зависимостей одной операции. Он не является перечнем дефектов Nuxt и не требует переписать все существующие обработчики. Наоборот, ограниченный разбор помогает выбрать обоснованный объём изменения вместо массовой замены похожих имён.

Почему явный импорт имеет значение

Release notes отдельно предупреждают: автоимпортированные helpers в Nuxt 4 пока относятся к h3, у которого другая форма event. Для нового пути нужны явные импорты из nuxt/server, включая defineEventHandler. Кроме того, некоторые одноимённые helpers отличаются поведением. Это не переименование каталога без изменения контракта.

Перед заменой запишите, что использует код: чтение тела, перенаправление, заголовки или другую нужную операцию. Затем сопоставьте её с актуальным описанием. Не переносите автоматическую замену на участок, который по назначению продолжает использовать другой поддерживаемый интерфейс.

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

Локально новый импорт может распознаваться, а задание сборки — работать в другом окружении. Сохраните версии ядра, CLI и Node в проверяемой поставке. Важно понимать не только, что установлено у разработчика, но и чем получают артефакт для рабочего размещения.

Цифры скорости старта из выпуска CLI не являются замером вашего проекта. Если это цель работы, выбирайте собственную операцию и одинаковые условия сравнения. Для проверки совместимости достаточно не выдавать скорость чужой минимальной установки за результат вашего сервиса.

Ограниченный порядок изменения серверного кода

1. Выберите конкретный обработчик и запишите его вход и результат.
2. Разделите серверные helpers, внутренние зависимости и бизнес-проверки.
3. Сверьте явные импорты и контракт event выбранного пути.
4. Зафиксируйте совместимое окружение ядра и CLI.
5. Проверьте успешный запрос, отказ доступа и ошибку данных.
6. Сохраните результат и отдельно перечислите непроверенные модули.

В разработке веб-приложения такая карта делает границы изменения понятными. Для API-интеграции сохраняйте прикладной контракт, а в поддержке сервера фиксируйте окружение выпуска. Новый публичный API полезен именно там, где команда понимает, какую зависимость он заменяет.