将Nuxt工程从3.x升级到最新的4.3.0

声明：作者声明此文章为原创，未经作者同意，请勿转载，若转载，务必注明本站出处，本平台保留追究侵权法律责任的权利。

全栈老韩

全栈工程师，擅长iOS App开发、前端（vue、react、nuxt、小程序&Taro）开发、Flutter、React Native、后端（midwayjs、golang、express、koa）开发、docker容器、seo优化等。

这篇文章记录一下我如何将我的Nuxt工程从3.x升级到最新的4.x版本，其中遇到一些坑，希望对大家有帮助。

我之前已经写过如何去打包和部署NextJs工程，这次我回过头来去处理我的另外一个项目，是使用Nuxt开发的前端项目，众所周知，如果要做一个SEO良好的项目，必不可少要用到服务端渲染，那么针对React语言，比较好的实践是使用NextJs，对于Vue项目，比较好的是选择Nuxt，我目前的项目都有使用到这2种类型的开发框架。

之前使用Nuxt是比较早的时候，那个时候Nuxt还是3.x版本，但是过了这么久，Nuxt做了非常多的版本升级，对于性能上的优化还是不少的，所以升级到最新版本是一个必不可少的步骤。这里我来介绍一下我工程中遇到的升级问题和流程。

一、升级Nuxt版本

升级前我的nuxt版本如下：

package.json 复制代码

...
"devDependencies": {
    ...
    "nuxt": "^3.9.0",
    ...
},
...

最新的Nuxt版本是：4.3.0
nuxt最新版本4.3.0

升级的话，我们可以直接在官网中查询到：https://nuxt.com/docs/4.x/getting-started/upgrade

需要使用的终端命令是：

terminal 复制代码

npx nuxt upgrade

但是直接去执行这个命令，版本号也只能限定到3.x版本系列的最高版本，而不是4.x版本。

比如我直接执行上面的终端命令，只能将我的^3.9.0升级到3.20.1。

所以我们要先修改nuxt的版本号为：

package.json 复制代码

...
"devDependencies": {
    ...
    "nuxt": "^4.3.0",
    ...
},
...

然后执行npm install终端命令，先安装4.3.0的版本.

最后再执行

terminal 复制代码

npx nuxt upgrade

终端会提示你是否要re-create node_modules和pakcage-lock.json，选择它，然后enter继续。

之后命令会将工程中的所有依赖和.nuxt升级到版本4.x的依赖。

二、scss的预处理配置

在以前的Nuxt 3.x版本中，我引入全局scss文件的时候，引入是下面这样的：

nuxt.config.ts 复制代码

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  compatibilityDate: '2026-02-04',
  ...
  css: ['~/assets/css/style.css'],
  ...
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@import "~/assets/css/global.scss";',
        },
      },
    },
  },
  ...
});

但是升级到4.x版本的时候这种预处理配置会报错:

terminal error 复制代码

ℹ Error: [sass] expected ";".
  ╷
1 │ @import "~/assets/css/global.scss";
  │                                       ^
  ╵
  app.vue 1:39  root stylesheet

 ⁃ (app.vue 1:39  root stylesheet:undefined:undefined:undefined:undefined)

必须要改成以下的形式：

nuxt.config.ts 复制代码

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  compatibilityDate: '2026-02-01',
  ...
  css: ['~/assets/css/style.css'],
  ...
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "~/assets/css/global.scss" as *;',
        },
      },
    },
  },
  ...
});

另外我提一句，在4.x版本中可以添加以下的描述：

nuxt.config.ts 复制代码

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  compatibilityDate: '2026-02-01',
...
});

看看它的介绍：
compatibilityDate说明

这个配置会影响到一些nitro服务端的预设值等，所以建议最好配置一下。

三、页面动态id修改

在之前的3.x版本中，我有一些页面使用了[:id].vue这样的配置，但是在4.x版本中已经不允许这么做了，所以如果你的项目中有这样的动态路由，也是一定要改写一下。

从[:id].vue改写为[id].vue，不要id前面的:冒号了。

以上就是我暂时遇到的一些升级问题，这样修改后，项目是能正常运行，且编译速度和渲染也有700ms左右的提升。

这里简单给大家做参考，希望对大家有帮助。

希望大家多多点赞、关注支持一下，您的点赞/关注是我更新的动力，谢谢。

发布于2026-02-04 07:12:40

浏览量48·

暂无评论，快来发表第一条评论吧