Изучите Nuxt с коллекцией из 100+ советов!
54.1K

Руководство по обновлению

Узнайте, как перейти на последнюю версию Nuxt.

Обновление Nuxt

Последний релиз

Чтобы обновить Nuxt до последней версии, используйте команду nuxi upgrade.

npx nuxi upgrade

Канал ночных релизов (Nightly Release)

Чтобы использовать последнюю сборку Nuxt и тестировать функции до их выхода, ознакомьтесь с информацией о канале ночных релизов.

В настоящее время тег latest канала ночных релизов отслеживает ветку Nuxt v4, а это значит, что сейчас в ней особенно вероятны изменения - будьте осторожны!Вы можете подключиться к ночным релизам ветки 3.x с помощью тега "nuxt": "npm:nuxt-nightly@3x".

Тестируем Nuxt 4

Nuxt 4 планируется выпустить после 14 июня или раньше (хотя, конечно, это зависит от того, будет ли достаточно времени после выхода основного релиза Nitro для надлежащего тестирования в сообществе, так что имейте в виду, что это не точная дата).

До тех пор, пока не будет выпущена версия Nuxt 4, можно тестировать многие из её изменений, несовместимых с предыдущими версиями, начиная с Nuxt версии 3.12+.

Посмотрите видео от Александра Лихтера, в котором рассказывается о том, как уже сейчас внедрить изменения Nuxt 4.

Внедрение Nuxt 4

Первым шагом необходимо обновить Nuxt до последней версии.

Затем вы можете установить compatibilityVersion для соответствия поведению Nuxt 4:

nuxt.config.ts
export default 
defineNuxtConfig
({
  
future
: {
    
compatibilityVersion
: 4,
  },
  // Чтобы снова включить все поведение Nuxt v3, установите следующие параметры:
  // srcDir: '.',
  // dir: {
  //   app: 'app'
  // },
  // experimental: {
  //   sharedPrerenderData: false,
  //   compileTemplate: true,
  //   resetAsyncDataToUndefined: true,
  //   templateUtils: true,
  //   relativeWatchPaths: true,
  //   defaults: {
  //     useAsyncData: {
  //       deep: true
  //     }
  //   }
  // },
  // unhead: {
  //   renderSSRHeadOptions: {
  //     omitLineBreaks: false
  //   }
  // }
})

Когда вы установите compatibilityVersion в 4, настройки по умолчанию во всей вашей конфигурации Nuxt изменятся, чтобы выбрать поведение Nuxt v4, но вы можете выборочно включить поведение Nuxt v3 при тестировании, следуя закомментированным строкам выше. Пожалуйста, пишите о проблемах, чтобы мы могли решить их в Nuxt или в экосистеме.

Миграция на Nuxt 4

Ломающие или значительные изменения, а также шаги по миграции для обеспечения обратной/прямой совместимости, будут отмечены здесь.

Этот раздел может быть изменен до выхода финального релиза, поэтому тестируете Nuxt 4, используя compatibilityVersion: 4.

Миграция с использованием Codemod

Чтобы упростить процесс обновления, мы объединились с командой Codemod для автоматизации многих этапов миграции с использованием некоторых codemods с открытым исходным кодом.

Если у вас возникнут какие-либо проблемы, сообщите о них команде Codemod с помощью npx codemod feedback 🙏

Полный список codemods Nuxt 4, подробную информацию о каждом из них, их источнике и различных способах их запуска можно найти в Реестре codemods.

Вы можете запустить все codemods, упомянутые в этом руководстве, используя следующий рецепт codemod:

npx codemod@latest nuxt/4/migration-recipe

Эта команда последовательно выполнит все codemods, с возможностью отменить выбор тех, которые вы не хотите запускать. Каждый codemod будет также указан ниже вместе с соответствующим изменением и может быть выполнен независимо.

Новая структура директорий

🚦 Уровень влияния: Значительный

Теперь Nuxt по умолчанию использует новую структуру каталогов с обратной совместимостью (если Nuxt обнаружит, что вы используете старую структуру, например, каталог верхнего уровня pages/, то новая структура не будет применяться).

👉 См. полный текст RFC

Что изменилось
  • в новом Nuxt по умолчанию srcDir теперь app/, и большинство вещей решается оттуда.
  • serverDir теперь по умолчанию имеет значение <rootDir>/server, а не <srcDir>/server.
  • layers/, modules/ и public/ по умолчанию разрешаются относительно <rootDir>.
  • при использовании Nuxt Content v2.13+, content/ разрешается относительно <rootDir>
  • добавлена новая директория dir.app, в которой мы ищем router.options.ts и spa-loading-template.html - по умолчанию это <srcDir>/.
Пример структуры папок v4.
.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
modules/
node_modules/
public/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts

👉 Более подробную информацию можно найти в PR, реализующем это изменение.

Причины таких изменений
  1. Производительность - размещение всего кода в корне репозитория приводит к проблемам со сканированием/включением папок .git/ и node_modules/ наблюдателями FS (файловой системы), что может значительно замедлить запуск на не-Mac ОС.
  2. Безопасность типов в IDE - server/ и остальное приложение работают в двух совершенно разных контекстах с разными глобальными импортами, и убедиться, что server/ не находится внутри той же папки, что и остальное приложение, — важный первый шаг к обеспечению хорошего автодополнения в вашей IDE.
Этапы миграции
  1. Создайте новую директорию с именем app/.
  2. Переместите в нее папки assets/, components/, composables/, layouts/, middleware/, pages/, plugins/ и utils/, а также app.vue, error.vue, app.config.ts. Если у вас есть папки app/router-options.ts или app/spa-loading-template.html, эти пути остаются прежними.
  3. Убедитесь, что папки nuxt.config.ts, content/, layers/, modules/, public/ и server/ находятся вне папки app/, в корне вашего проекта.
Вы можете автоматизировать эту миграцию, запустив npx codemod@latest nuxt/4/file-structure

Однако миграция не является обязательной. Если вы хотите сохранить текущую структуру папок, Nuxt автоматически определит ее. (Если это не так, пожалуйста, поднимите вопрос.) Единственное исключение - если у вас уже есть собственный srcDir. В этом случае вы должны знать, что ваши папки modules/, public/ и server/ будут разрешены из вашего rootDir, а не из вашего пользовательского srcDir. Вы можете отменить это, настроив dir.modules, dir.public и serverDir, если вам это необходимо.

Вы также можете принудительно использовать структуру папок v3 с помощью следующей конфигурации:

nuxt.config.ts
export default defineNuxtConfig({
  // Это вернет новый srcDir по умолчанию из `app` обратно в вашу корневую директорию
  srcDir: '.',
  // Это определяет префикс директории для `app/router.options.ts` и `app/spa-loading-template.html`.
  dir: {
    app: 'app'
  }
})

Общие данные пререндера

🚦 Уровень воздействия: Средний

Что изменилось

Мы включили ранее экспериментальную возможность обмена данными из вызовов useAsyncData и useFetch на разных страницах. См. оригинальный PR.

Причины таких изменений

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

Например, если ваш сайт требует вызова useFetch для каждой страницы (например, для получения навигационных данных для меню или настроек сайта из CMS), эти данные будут получены только один раз при предварительном рендеринге первой страницы, которая их использует, а затем кэшированы для использования при предварительном рендеринге других страниц.

Этапы миграции

Убедитесь, что любой уникальный ключ ваших данных всегда можно разрешить в те же самые данные. Например, если вы используете useAsyncData для получения данных, относящихся к определенной странице, вы должны предоставить ключ, который однозначно соответствует этим данным. (Функция useFetch должна сделать это автоматически).

app/pages/test/[slug].vue
// Это было бы небезопасно на динамической странице (например, `[slug].vue`), потому что slug маршрута разный
// в получаемых данных, но Nuxt не может этого знать, потому что это не отражено в ключе.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// Вместо этого следует использовать ключ, который однозначно идентифицирует получаемые данные.
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

Но вы все равно можете отключить эту функцию с помощью:

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
sharedPrerenderData
: false
  }
})

Значения по умолчанию data и error в useAsyncData и useFetch

🚦 Уровень воздействия: Минимальный

Что изменилось

Объекты data и error, возвращаемые из useAsyncData, теперь будут по умолчанию иметь значение undefined.

Причины таких изменений

Ранее data инициализировалась в null, но сбрасывалась в clearNuxtData в undefined. error инициализировался в null. Это изменение призвано обеспечить большую согласованность.

Этапы миграции

Если вы проверяли, являются ли data.value или error.value null, вы можете обновить эти проверки, чтобы проверять на undefined вместо этого.

Вы можете автоматизировать этот шаг, запустив npx codemod@latest nuxt/4/default-data-error-value

Если у вас возникнут какие-либо проблемы, вы можете вернуться к прежнему поведению с помощью:

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
defaults
: {
      
useAsyncData
: {
        
value
: 'null',
        
errorValue
: 'null'
      }
    }
  }
})

Пожалуйста, сообщите о проблеме, если вы делаете это, так как мы не планируем сохранять эту настройку.

Удаление устаревших значений boolean для опции dedupe при вызове refresh в useAsyncData и useFetch

🚦 Уровень воздействия: Минимальный

Что изменилось

Ранее в refresh можно было передавать dedupe: boolean. Это были псевдонимы cancel (true) и defer (false).

app.vue
const { 
refresh
 } = await 
useAsyncData
(async () => ({ 
message
: 'Привет, Nuxt 3!' }))

async function 
refreshData
 () {
  await 
refresh
({ 
dedupe
: true })
}
Причины таких изменений

Эти псевдонимы были удалены для большей ясности.

Проблема возникла при добавлении dedupe в качестве опции к useAsyncData, и мы удалили булевы значения, поскольку они оказались противоположными.

refresh({ dedupe: false }) означало "не отменять существующие запросы в пользу нового". Но передача dedupe: true в опциях useAsyncData означает "не делать никаких новых запросов, если есть существующий отложенный запрос". (См. PR.)

Этапы миграции

Миграция должна быть простой:

  const { refresh } = await useAsyncData(async () => ({ message: 'Привет, Nuxt 3!' }))
  
  async function refreshData () {
-   await refresh({ dedupe: true })
+   await refresh({ dedupe: 'cancel' })

-   await refresh({ dedupe: false })
+   await refresh({ dedupe: 'defer' })
  }
Вы можете автоматизировать этот шаг, запустив npx codemod@latest nuxt/4/deprecated-dedupe-value

Соблюдайте значения по умолчанию при очистке data в useAsyncData и useFetch

🚦 Уровень воздействия: Минимальный

Что изменилось

Если вы указали собственное значение default для useAsyncData, то теперь оно будет использоваться при вызове clear или clearNuxtData и будет сбрасываться до значения по умолчанию, а не просто сниматься.

Причины таких изменений

Часто пользователи задают соответствующее пустое значение, например, пустой массив, чтобы избежать необходимости проверки на null/undefined при итерации по нему. Это должно соблюдаться при сбросе/очистке данных.

Этапы миграции

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

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
resetAsyncDataToUndefined
: true,
  }
})

Пожалуйста, сообщите о проблеме, если вы делаете это, так как мы не планируем сохранять эту настройку.

Поверхностная реактивность данных в useAsyncData и useFetch

🚦 Уровень воздействия: Минимальный

Объект data, возвращаемый при использовании useAsyncData, useFetch, useLazyAsyncData и useLazyFetch, теперь представляет собой shallowRef, а не ref.

Что изменилось

При получении новых данных все, что зависит от data, все равно будет реактивным, потому что весь объект будет заменен. Но если ваш код изменит свойство внутри этой структуры данных, это не вызовет никакой реактивности в вашем приложении.

Причины таких изменений

Это дает значительное повышение производительности для глубоко вложенных объектов и массивов, поскольку Vue не нужно следить за изменением каждого отдельного свойства/массива. В большинстве случаев data также должна быть неизменяемой.

Этапы миграции

В большинстве случаев миграция не требуется, но если вы полагаетесь на реактивность объекта данных, то у вас есть два варианта:

  1. Вы можете точечно выбрать глубокую реактивность на основе каждого компонента: 
    - const { data } = useFetch('/api/test')
+ const { data } = useFetch('/api/test', { deep: true })
  2. Вы можете изменить поведение по умолчанию в масштабах всего проекта (не рекомендуется):
    nuxt.config.ts
    export default 
    defineNuxtConfig
    ({
      
    experimental
    : {
        
    defaults
    : {
          
    useAsyncData
    : {
            
    deep
    : true
          }
    }
  }
})
При необходимости вы можете автоматизировать этот шаг, запустив npx codemod@latest nuxt/4/shallow-function-reactivity

Абсолютные пути наблюдения в builder:watch

🚦 Уровень воздействия: Минимальный

Что изменилось

Nuxt-хук builder:watch теперь выдает путь, который является абсолютным, а не относительным к srcDir вашего проекта.

Причины таких изменений

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

Этапы миграции

Мы уже проактивно мигрировали публичные модули Nuxt, которые, как нам известно, используют этот хук. Смотрите issue #25339.

Однако, если вы являетесь автором модуля, использующего хук builder:watch, и хотите сохранить обратную/будущую совместимость, вы можете использовать следующий код, чтобы убедиться, что ваш код работает одинаково как в Nuxt v3, так и в Nuxt v4:

+ import { relative, resolve } from 'node:fs'
 // ...
 nuxt.hook('builder:watch', async (event, path) => {
+   path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
   // ...
 })
Вы можете автоматизировать этот шаг, запустив npx codemod@latest nuxt/4/absolute-watch-path

Удаление объекта window.__NUXT__

Что изменилось

Мы удаляем глобальный объект window.__NUXT__ после того, как приложение завершает гидратацию.

Причины таких изменений

Это открывает путь к шаблонам мульти-приложений (#21635) и позволяет нам сосредоточиться на единственном способе доступа к данным приложения Nuxt - useNuxtApp().

Этапы миграции

Данные по-прежнему доступны, но доступ к ним можно получить с помощью useNuxtApp().payload:

- console.log(window.__NUXT__)
+ console.log(useNuxtApp().payload)

Сканирование индекса директории

🚦 Уровень воздействия: Средний

Что изменилось

Дочерние папки в папке middleware/ также проверяются на наличие файлов index, и теперь они также регистрируются как middleware в вашем проекте.

Причины таких изменений

Nuxt автоматически сканирует ряд папок, включая middleware/ и plugins/.

Дочерние папки в вашей папке plugins/ сканируются на наличие файлов index, и мы хотели сделать это поведение последовательным для разных сканируемых директорий.

Этапы миграции

Скорее всего, миграция не нужна, но если вы хотите вернуться к предыдущему поведению, вы можете добавить хук для фильтрации этих middleware:

export default defineNuxtConfig({
  hooks: {
    'app:resolve'(app) {
      app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
    }
  }
})

Изменения в компиляции шаблонов

🚦 Уровень воздействия: Минимальный

Что изменилось

Ранее Nuxt использовал lodash/template для компиляции шаблонов, расположенных в файловой системе, используя формат/синтаксис файла .ejs.

Кроме того, мы предоставили несколько утилит для шаблонов (serialize, importName, importSources), которые можно было использовать для генерации кода внутри этих шаблонов, а теперь они удалены.

Причины таких изменений

В Nuxt v3 мы перешли на 'виртуальный' синтаксис с функцией getContents(), которая является гораздо более гибкой и производительной.

Кроме того, у lodash/template была целая череда проблем с безопасностью. Они не совсем относятся к проектам Nuxt, поскольку используются во время сборки, а не во время выполнения, и в доверенном коде. Тем не менее они все еще появляются в аудитах безопасности. Более того, lodash - это большая зависимость, и она не используется в большинстве проектов.

Наконец, предоставление функций сериализации кода непосредственно в Nuxt не является идеальным решением. Вместо этого мы поддерживаем такие проекты, как unjs/knitwork, которые могут быть зависимы от вашего проекта, и где о проблемах безопасности можно сообщать/решать напрямую, не требуя обновления самого Nuxt.

Этапы миграции

Мы подняли PR для обновления модулей с использованием синтаксиса EJS, но если вам нужно сделать это самостоятельно, у вас есть три обратно/будуще совместимые альтернативы:

  • Перенос логики интерполяции строк непосредственно в getContents().
  • Использование пользовательской функции для обработки замены, как, например, в https://github.com/nuxt-modules/color-mode/pull/240.
  • Продолжение использования lodash, как зависимости от вашего проекта, а не Nuxt:
+ import { readFileSync } from 'node:fs'
+ import { template } from 'lodash-es'
  // ...
  addTemplate({
    fileName: 'appinsights-vue.js'
    options: { /* some options */ },
-   src: resolver.resolve('./runtime/plugin.ejs'),
+   getContents({ options }) {
+     const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
+     return template(contents)({ options })
+   },
  })

Наконец, если вы используете шаблонные утилиты (serialize, importName, importSources), вы можете заменить их на утилиты из knitwork следующим образом:

import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'

const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"{(.+)}"(?=,?$)/gm, r => JSON.parse(r).replace(/^{(.*)}$/, '$1'))

const importSources = (sources: string | string[], { lazy = false } = {}) => {
  return toArray(sources).map((src) => {
    if (lazy) {
      return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
    }
    return genImport(src, genSafeVariableName(src))
  }).join('\n')
}

const importName = genSafeVariableName
Вы можете автоматизировать этот шаг, запустив npx codemod@latest nuxt/4/template-compilation-changes

Удаление экспериментальных функций

🚦 Уровень воздействия: Минимальный

Что изменилось

Четыре экспериментальные функции больше не настраиваются в Nuxt 4:

  • experimental.treeshakeClientOnly будет true (по умолчанию с v3.0)
  • experimental.configSchema будет true (по умолчанию с v3.3)
  • experimental.polyfillVueUseHead будет false (по умолчанию с v3.4)
  • experimental.respectNoSSRHeader будет false (по умолчанию с v3.4)
  • vite.devBundler больше не настраивается - по умолчанию будет использоваться vite-node.
Причины таких изменений

Эти параметры уже давно имеют текущие значения, и у нас нет причин полагать, что они должны оставаться настраиваемыми.

Этапы миграции
  • polyfillVueUseHead реализуется на территории пользователя с помощью этого плагина
  • respectNoSSRHeader реализуется на территории пользователя с помощью серверной middleware

Nuxt 2 против Nuxt 3+

В таблице ниже приведено краткое сравнение между 3 версиями Nuxt:

Feature / VersionNuxt 2Nuxt BridgeNuxt 3+
Vue223
Стабильность😊 Стабильный😊 Стабильный😊 Стабильный
Производительности🏎 Быстрый✈️ Быстрее🚀 Быстрейший
Движок Nitro❌✅✅
Поддержка ESM🌙 Частично👍 Лучше✅
TypeScript☑️ Opt-in🚧 Частично✅
Composition API❌🚧 Частично✅
Options API✅✅✅
Автоимпорт компонент✅✅✅
<script setup> синктаксис❌🚧 Частично✅
Автоимпорты❌✅✅
webpack445
Vite⚠️ Частично🚧 Частично✅
Nuxi CLI❌ Устарел✅ nuxi✅ nuxi
Статические сайты✅✅✅

С Nuxt 2 на Nuxt 3+

Руководство по миграции содержит пошаговое сравнение функций Nuxt 2 с функциями Nuxt 3+ и рекомендации по адаптации вашего текущего приложения.

Ознакомьтесь с руководством по переходу с Nuxt 2 на Nuxt 3.

С Nuxt 2 на Nuxt Bridge

Если вы предпочитаете постепенно переводить свои приложения Nuxt 2 на Nuxt 3, вы можете использовать Nuxt Bridge. Nuxt Bridge - это уровень совместимости, который позволяет вам использовать функции Nuxt 3+ в Nuxt 2 с помощью механизма opt-in.

Переход с Nuxt 2 на Nuxt Bridge.

Тестирование

Как протестировать ваше приложение Nuxt.

Автоматические импорты

Nuxt автоматически импортирует компоненты, композаблы, вспомогательные функции и API Vue.