[[email protected]] 文件 - 起步

[ChaoLiou]

安裝

先決條件

• node - 至少 v10.13, 建議安裝最新的 LTS 版本
• 文字編輯器, 建議 VSCode 和 Vetur 擴充工具, 或只用 WebStorm
• terminal, 建議用 VSCode 的 integrated terminal, 或只是 WebStorm terminal

---

用 create-nuxt-app

• 要快速起步, 可以用 create-nuxt-app
• 確認有安裝 npx (npx 從 NPM 5.2.0 開始會預設加進來) 或是 npm v6.1 或是 yarn.

npx create-nuxt-app <專案名稱>

npm init nuxt-app <專案名稱>

yarn create nuxt-app <專案名稱>

• 會問一些問題(名稱, Nuxt 選項, UI 框架, TypeScript, linter, 測試框架, 等等)
• 一旦所有問題都回答, 就會安裝所有 dependencies. 下一步是 cd 到專案資料夾並啟動:

cd <專案名稱>
npm run dev

cd <專案名稱>
yarn dev

• app 就會在 http://localhost:3000 運行.

---

手動安裝

• 從頭建立一個 Nuxt.js 專案只需要一個檔案和一個資料夾
• 會用 terminal 建立資料夾和檔案

設置你的專案

• 建立一個空的資料夾, 以專案名稱命名並 cd 到專案內:

mkdir <專案名稱>
cd <專案名稱>

• 建立 package.json:

touch package.json

• 填入 package.json 的內容:

{
  "name": "我的 app",
  "scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "start": "nuxt start"
  }
}

• script 定義 Nuxt.js 指令, 會用指令 npm run <指令> 或是 yarn <指令> 啟動
• 甚麼是 package.json?
  • package.json 就像是專案的 ID 卡. 包含了所有專案的 dependencies.

安裝 Nuxt

• 一旦建立好 package.json, 透過 npm 或是 yarn 將 nuxt 加到專案:

npm install nuxt

yarn add nuxt

• 指令會將 nuxt 當作一個 dependency 加到專案的 package.json. 再建立 node_modules/, 那裡是儲存所有 安裝套件 和 dependencies 的地方.

也會建立 yarn.lock 或 package-lock.json, 確保安裝的套件一致, 以及 dependencies 是可相容的.

建立你的第一頁

• Nuxt.js 將每個 pages/ 底下的 *.vue, 轉化成 app route.
• 在專案建立 pages/:

mkdir pages

• 然後在 pages/ 底下建立 index.vue:

touch pages/index.vue

• 這頁叫做 index.vue 是因為當 app 打開時是 Nuxt 顯示的預設首頁
• 在編輯器打開 index.vue, 並加入以下內容:

<!-- pages/index.vue -->
<template>
  <h1>Hello world!</h1>
</template>

啟動專案

• 在 terminal 輸入以下其中一個指令執行專案:

npm run dev

yarn dev

當要以開發模式 運行 app 時, 使用 dev 指令

• app 會在 http://localhost:3000 上運行
• 在 terminal 點擊連結, 瀏覽器就會打開, 然後就會看到 "Hello World" 的文字.

當以開發模式啟動 Nuxt.js, 他會監聽大部分資料夾裡面的檔案異動, 所以當加入新頁面時, 不需要重啟 app

當執行 dev 指令, 他會建立 .nuxt/. 這個資料夾要被版控系統忽略. 要忽略檔案, 可以在最上層資料夾建立一個 .gitignore 並加上 .nuxt 的內容.

再一個步驟

• 在 pages/ 建立一個叫做 fun.vue 的頁面
• 加上 <template><h1>fun page</h1></template> 的內容
• 然後到瀏覽器輸入 http://localhost:3000/fun 看新頁面

建立一個叫做 more-fun/ 並放入 index.vue 檔案 等同於 直接建立一個 more-fun.vue 檔案.

---

---

routing

自動化的 routes

• 大多數網站都會超過一頁(即 首頁, 關於頁, 聯繫頁, 等等). 為了要看到這些頁面, 需要一個 router. 這就是 vue-router 的切入點. 若使用 Vue app, 必須設置設定檔(即為 router.js), 並手動加入所有 route. 而 Nuxt.js 會自動化產生 vue-router 設定, 依據 pages/ 內的 Vue 檔案. 這表示不需要寫 router 設定. Nuxt.js 還會自動做 code-splitting.
• 換句話說, 所有要做的就只有在 pages/ 中建立 .vue.

---

導向

• 要在 app 頁面間導向, 使用 NuxtLink 元件. 這個元件是包含在 Nuxt.js, 所以不需要像其他元件一樣還要匯入. 他類似於 HTML <a> 標籤, 但不是使用 href="/about", 而是用 to="/about". 如果曾用過 vue-router, 可以把 <NuxtLink> 想像成 <RouterLink>.
• 要到 pages/ 裡 index.vue 頁面的一個簡單連結:

<!-- pages/index.vue -->
<template>
  <NuxtLink to="/">首頁</NuxtLink>
</template>

• 對於所有網站的內部連結, 使用 <NuxtLink>. 如果連結要到其他網站, 用 <a> 標籤.

<!-- pages/index.vue -->
<template>
  <main>
    <h1>首頁</h1>
    <NuxtLink to="/about">
      關於 (內部連結, 屬於 Nuxt App)
    </NuxtLink>
    <a href="https://nuxtjs.org">外部連結到其他網頁</a>
  </main>
</template>

---

---

資料夾結構

• 預設的 Nuxt.js app 結構, 其用意是提供包含小型和大型 app 的起始專案. 不過可以自由按照個人喜好去組織 app, 如果需要, 可以再建立其他資料夾.
• 一起來建立還缺的資料夾和檔案:

mkdir components assets static
touch nuxt.config.js

• 當建立 Nuxt.js app, 這些都是主要會用到的資料夾和檔案.

資料夾

pages/

• pages/ 包含 app 的 view 和 route.

components/

• components/ 是放所有 Vue.js 元件的地方, 再將他們匯入到頁面中.
• 在 Nuxt.js, 可以建立元件, 並自動匯入到 .vue, 表示不需要在 script 手動匯入. 若有將 components 設為 true, Nuxt.js 會掃描並自動匯入.

assets/

• assets/ 包含未編譯的 asset 檔案, 像是 樣式檔, 圖片檔, 或是字型檔.

static/

• static/ 是直接映射到 server 根目錄, 裡面的檔案必須屬於名稱保持不變的(如 robot.txt) 或是內容幾乎不會改變的(如 favicon).

nuxt.config.js

• nuxt.config.js 是 Nuxt.js 的單點設定. 如果要加入 module 或是覆蓋預設值, 可以在這裡修改.

package.json 檔案

• package.json 包含所有 dependencies 和 app 的指令 script.

---

更多關於專案結構

• 還有其他資料夾和檔案, 包括 content/, layout/, middleware/, modules/, plugins/ 和 store/.

---

---

指令和部署

• Nuxt.js 的指令, 包含開發和生產

在 package.json 使用

• 要把這些指令放在 package.json:

{
  "scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "start": "nuxt start",
    "generate": "nuxt generate"
  }
}

• 然後透過 yarn <指令> 或 npm run <指令> 啟動.

---

開發環境

• 要在開發模式以 Hot Module Replacement(HMR) 將 Nuxt 啟動於 http://localhost:3000 上:

npm run dev

yarn dev

---

指令列表

• 根據 target 執行不同指令:

指令\target	server(預設)	static
nuxt dev	啟動開發 server	啟動開發 server
nuxt build	生產版本 以 webpack 建置和優化 app	-
nuxt generate	-	建立 app, 將所有 route 產生成多份 HTML, 再靜態輸出 dist/(用於靜態託管服務)
nuxt start	啟動生產 server 用於 Node.js 託管服務, 像是 Heroku, Digital Ocean	對外服務 dist/, 如同靜態託管服務(Netlify, Vercel, Surge), 用於部署前測試.

生產部署

Server 部署

• 要部署 Server-Side Rendering(SSR) app, 使用 target: server

npm run build

yarn build

• Nuxt.js 會建立一個 .nuxt/ 並準備好所有要部署到 server 託管服務上的東西.

建議將 .nuxt 放進 .npmignore 或 .gitignore.

• 一旦建立 app, 可以用 start 指令啟動 app 的生產版本.

npm run start

yarn start

靜態部署(預先生成)

• Nuxt.js app 可以在任何靜態託管服務上.
• 要部署靜態生成網站, 確認 nuxt.config.js 裡有 target: static.(Nuxt >= 2.13)

// nuxt.config.js
export default {
  target: 'static'
}

npm run generate

yarn generate

• Nuxt.js 會建立一個 dist/ 並準備好所有要部署到靜態託管服務上的東西.
• 因為 Nuxt v2.13 有安裝爬蟲, 所以現在使用指令 nuxt generate, 會爬取連結標籤, 並根據那些連結生產 route.

當使用 Nuxt <= v2.12, generate 指令會忽略動態的 route.

當使用 nuxt generate 產生 app, asyncData 和 fetch 接到的 context 不會有 req 和 res.

• 錯誤造成的失敗
  • 當有頁面遇到錯誤時, 要讓 CI/CD 的部署或建置失敗, 需要回傳一個 非零 的狀態碼, 可以使用 --fail-on-error 參數.

npm run generate --fail-on-error

yarn generate --fail-on-error