跳到主要內容
madebyw
前端開發

Nuxt 4 建立專案：和 Nuxt 3 有哪些不同

整理 Nuxt 4 建立專案的基本流程與目錄結構，並對照 Nuxt 3 的差異，包括 app/ 目錄、路徑別名、TypeScript，以及目前常用的 ESLint 與 Tailwind CSS 4 設定。

W

  • Nuxt 4 延續 Nuxt 3 的 Vue 3、檔案路由、自動匯入與 Nitro，使用方式沒有全部重來。
  • 最大的差異反而是：

Nuxt 4 把前端程式集中到 app/ 目錄，讓 client、server 與共用程式的界線更清楚。

  • 這篇重新整理一次 Nuxt 4 新專案的建立方式，並對照 Nuxt 3 哪些地方不同。

建立 Nuxt 4 專案

目前官方建議使用 Node.js 22 以上。 建立專案：

npm create nuxt@latest my-app

進入專案：

cd my-app

啟動：

npm run dev

開發環境預設：

http://localhost:3000

常見指令：

npm run dev
npm run build
npm run preview

Nuxt CLI 也可以使用：

npx nuxt dev
npx nuxt build
npx nuxt preview

以前 Nuxt 3 筆記常看到：

npx nuxi@latest init my-app

現在建立新專案直接使用：

npm create nuxt@latest my-app

即可。

Nuxt 4 的目錄結構

Nuxt 4 新專案主要結構：

my-app/
├── app/
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── layouts/
│   ├── middleware/
│   ├── pages/
│   ├── plugins/
│   ├── utils/
│   ├── app.vue
│   ├── app.config.ts
│   └── error.vue
│
├── public/
├── server/
├── shared/
├── nuxt.config.ts
├── package.json
└── tsconfig.json

如果有使用 Nuxt Content、Layers 或自訂 Module，也可能看到：

content/
layers/
modules/

最大差異：前端程式搬進 app/

Nuxt 3 常見：

my-app/
├── assets/
├── components/
├── composables/
├── layouts/
├── middleware/
├── pages/
├── plugins/
├── server/
├── app.vue
└── nuxt.config.ts

Nuxt 4：

my-app/
├── app/
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── layouts/
│   ├── middleware/
│   ├── pages/
│   ├── plugins/
│   └── app.vue
│
├── server/
├── shared/
└── nuxt.config.ts

可以簡單理解成：

app/
→ Vue 前端程式

server/
→ Nitro 後端程式

shared/
→ 前後端都可以使用的程式

public/
→ 不經過 Vite 處理的靜態檔案

這是 Nuxt 4 最值得記住的架構改動。

路徑別名也跟著改變

Nuxt 4 預設：

~/
@/

指向：

app/

所以：

import something from '~/utils/something'

實際上是：

app/utils/something.ts

如果要從專案根目錄引用，可以使用：

~~/
@@/

例如：

import config from '~~/config/site'

簡單記：

~/   → app/
~~/  → 專案根目錄

shared/：前後端共用

Nuxt 4 新增 shared/，適合放前端與 Nitro server 都需要使用的程式。

例如：

shared/
├── types/
└── utils/

// shared/utils/formatPrice.ts

export function formatPrice(value: number) {
  return value.toLocaleString('zh-TW')
}

這類沒有依賴：

window
document
navigator

也沒有依賴 Node server API 的純函式，就很適合放在 shared/。

TypeScript

  • Nuxt 本身就有 TypeScript 支援。
  • 如果要執行完整型別檢查，可以安裝：
npm install -D typescript vue-tsc

然後：

npx nuxt typecheck

Nuxt 4 會為不同執行環境產生獨立的 TypeScript 設定，例如：

.nuxt/tsconfig.app.json
.nuxt/tsconfig.server.json
.nuxt/tsconfig.shared.json
.nuxt/tsconfig.node.json

一般開發不需要自己修改這些檔案。

這樣做的好處是：

app/
→ 瀏覽器 / Vue 環境

server/
→ Server 環境

shared/
→ 兩邊都可以使用

IDE 的型別判斷會比以前更清楚。

ESLint

這不是 Nuxt 4 本身的 breaking change，而是目前 Nuxt + ESLint 的推薦方式已經改成 flat config。

可以使用 Nuxt 官方 ESLint module：

npx nuxi module add eslint

或手動安裝：

npm install -D @nuxt/eslint eslint typescript

nuxt.config.ts：

export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ]
})

專案根目錄使用：

eslint.config.mjs

例如：

import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt({
  rules: {
    'vue/multi-word-component-names': 'off'
  }
})

以前常見的：

.eslintrc.js
@nuxtjs/eslint-config-typescript

新專案就不需要再照舊筆記設定。

Tailwind CSS 4

這也不是 Nuxt 4 本身的改動，而是 Tailwind CSS 4 的新設定方式。

安裝：

npm install tailwindcss @tailwindcss/vite

nuxt.config.ts：

import tailwindcss from '@tailwindcss/vite'

export default defineNuxtConfig({
  css: [
    '~/assets/css/main.css'
  ],

  vite: {
    plugins: [
      tailwindcss()
    ]
  }
})

建立：

app/assets/css/main.css

內容：

@import "tailwindcss";

之後就可以直接使用：

<template>
  <h1 class="text-3xl font-bold">
    Hello Nuxt 4
  </h1>
</template>

Tailwind CSS 4 已不需要以前常見的：

tailwind.config.js
content: [...]

基本主題設定也可以直接使用 CSS 的 @theme。

Nuxt 3 與 Nuxt 4 對照

項目Nuxt 3Nuxt 4
建立新專案npx nuxi@latest initnpm create nuxt@latest
前端程式專案根目錄app/
pages//pages/app/pages
components//components/app/components
composables//composables/app/composables
layouts//layouts/app/layouts
plugins//plugins/app/plugins
Server/server/server
前後端共用自己安排/shared
~/專案 source 根目錄預設指向 /app
TypeScript單一主要設定app / server / shared 分離

ESLint 與 Tailwind 則比較適合理解成：

Nuxt 3 時期常見舊專案
→ .eslintrc
→ Tailwind 3
→ tailwind.config.js

現在的新專案工具鏈
→ ESLint flat config
→ @nuxt/eslint
→ Tailwind CSS 4
→ @tailwindcss/vite

它們不是 Nuxt 4 本身強制改變的功能。

哪些東西沒有變

Nuxt 3 學過的大部分核心概念，在 Nuxt 4 還是一樣。

例如：

檔案系統路由

app/pages/index.vue
→ /

app/pages/about.vue
→ /about

app/pages/users/[id].vue
→ /users/:id

<NuxtLink to="/about">
  About
</NuxtLink>

NuxtPage

<NuxtPage />

Layout

<NuxtLayout>
  <NuxtPage />
</NuxtLayout>

definePageMeta

definePageMeta({
  layout: 'default'
})

自動載入

components/
composables/
utils/
plugins/

仍然有 Nuxt 的自動掃描與載入機制。

所以從 Nuxt 3 升到 Nuxt 4，並不是重新學一次 Nuxt。

最主要只是先習慣：

以前
pages/
components/
composables/

現在
app/pages/
app/components/
app/composables/

小結

如果是新建立 Nuxt 4 專案，可以先記：

npm create nuxt@latest my-app

以及新的目錄分工：

app/
→ Vue 前端

server/
→ Nitro 後端

shared/
→ 前後端共用

public/
→ 靜態檔案

對從 Nuxt 3 過來的人來說，app/ 目錄是最明顯、也最需要先習慣的改變。

路由、Layout、Component、Composable、Plugin 等核心概念基本上都還在，只是檔案位置搬到了 app/ 底下。

參考資料

分享這篇
X Facebook LINE Threads