18 建立 Nuxt 3 開發環境 + 專案初始化與目錄結構說明

2025 iThome 鐵人賽

DAY 18

Modern Web

設計 x 開發：從 Figma 到 Vue，打造 LINE 互動形象網站！系列第 18 篇

17th鐵人賽

jingyi_rd

2025-08-25 12:03:46

150 瀏覽

分享至

前言

在前篇分享了到 Nuxt 的優勢與應用情境，再來要分享如何建立 Nuxt 專案，與介紹專案整體的目錄結構。
如果是第一次使用 Nuxt，這篇可以作為不錯的起點。
若之前有用過 Vue CLI 或 Vite，也會發現 Nuxt 的架構其實非常貼近現代開發者的習慣，並在此基礎上進行了優化。

建立開發環境

在前面我們已經安裝 Node.js，這裡直接執行 npm 指令安裝，開啟 VS Code 選擇上方「 ••• 」→「終端機」→「新增終端」，輸入以下指令：

cd  <到要放專案的資料夾>
npm create nuxt <專案名稱>

安裝所有套件。

cd <跟專案同位置>  // 確認當前位置與package.json同一層，如果當前位置正確可以不做。
npm i

npm run dev 啟動本地伺服器運行專案，瀏覽器輸入Local:網址 http://localhost:3000/ 就可以看到畫面囉！

專案結構說明

專案建立好後，先來了解Nuxt整體專案目錄的架構，有助於後續開發時知道各個資料檔案要歸類在哪裡，下方介紹每個資料夾要放入哪些檔案：

2025_liff_in_nuxt/
├── .nuxt/                 # Nuxt開發中，根據目錄結構生成。
├── .output/               # Nuxt build 後的輸出目錄（用於部署）
├── .env                   # 環境配置檔
├── assets/                # 靜態資源
├── components/            # Vue 元件
├── composables/           # 邏輯函式
├── content/               # 資料檔案
├── layouts/               # 自訂佈局
├── middleware/            # 中介層邏輯
├── pages/                 # 頁面檔案
├── plugins/               # 套件
├── public/                # 靜態公開檔案
├── server/                # 放後端邏輯
│   └── api/
│       └── order.js       # 對應 /api/order
├── app.vue                # Nuxt 應用入口點
├── nuxt.config.ts         # Nuxt 設定檔（支援 TypeScript）
├── package.json           # 套件與指令設定
├── tsconfig.json          # TypeScript 設定
└── README.md              # 專案說明

.nuxt：Nuxt 使用這個目錄來產生應用程式，請不要手動更改該目錄內所有內容。
.output：npm run build 時會把整個應用程式編譯、打包，產出到該資料夾。
.env：設定環境變數的檔案。
assets：放置需要「參與編譯」的資源，例如需經過轉譯或處理的圖片、字型、樣式檔等，通常會透過 CSS 的 url() 或 import 方式引入。
components：放置會重複使用的元件，例如按鈕、卡片、提示區塊等，在這個資料夾的檔案 Nuxt 會自動做引入，根據檔案路徑自動產生元件名稱，不需要再寫 import。
composables：放置自訂的功能函式或 hook，例如 useRuntimeConfig()、useState()，在這個資料夾的檔案 Nuxt 也會自動做引入。
content：裡面可以放例如 .md、.json、.yml、.csv 等內容檔案，Nuxt 會自動讀取這些檔案並轉換成可查詢的資料，讓你能在Vue 元件或頁面中以 內容管理（CMS） 的方式使用它們，但如果專案沒安裝 @nuxt/content，這個資料夾就不會有任何作用。
layouts：設定每個SFC要適用的整體佈局，例如前台跟後台的導覽列基本上不同，這時候就可以分 public.vue 、dashboard.vue 分別設定在不同的layout裡。
middleware：「路由的中介層」使用者到達某個特定頁面之前要執行的程式，例如判斷是否有登入、切換語言等。
pages：放每個頁面的位置，例如 login.vue、order.vue 等，會自動建立路由。
plugins：用來初始化第三方套件或進行全域設定。放在此目錄的檔案會在 Nuxt 專案執行階段（runtime）自動加載，可以用來載入例如 Element Plus、SweetAlert2 等外部套件，並透過 defineNuxtPlugin() 的 provide 方法，將功能注入到 NuxtApp，讓套件透過 useNuxtApp() 在元件內可以使用。
public：放置不需要經過編譯，檔案名稱固定，要讓瀏覽器直接能訪問的靜態公開檔案，例如 <img src="/images/photo.jpg" />的 photo.jpg 圖檔等。
server：Nuxt 專案中用來放置後端邏輯與 API 函式的資料夾。server/middleware/ 撰寫中介層邏輯，透過 Nitro 處理 SSR 與 API 之間的請求；Nuxt 採用 file-based routing（檔案自動路由機制），它會自動把 server/api/ 底下新增 .js 或 .ts 檔案，自動被註冊為一個 API 路由端點。
❕這邊提醒，如果將檔案直接放在 server/ 根目錄，就不會被自動執行或路由掛載，也就是不會自動當作 API 路由註冊哦。
app.vue：Nuxt 應用入口點，建立專案時自動包含的一個預設元件。
nuxt.config.ts：整個 Nuxt 專案的設定檔，包含套件、meta 標籤、自動引入路徑、路由、CSS 等。
package.json：管理指令與專案的套件，可在此查看套件版本。
tsconfig.json：是 TypeScript 的設定檔。即使你的 Nuxt 專案使用的是 JavaScript，這份檔案也會存在。
README.md：專案的介紹說明，語法採用markdown。可放置在最外層，專案部署到github時在下方會直接呈現介紹。