跳到內容
App Router開始使用安裝

如何設定新的 Next.js 專案

系統需求

  • Node.js 18.18 或更高版本。
  • 支援 macOS、Windows (包含 WSL) 和 Linux。

自動安裝

我們建議使用 create-next-app 開始新的 Next.js 應用程式，它會自動為您設定一切。要建立專案，請執行

終端機
npx create-next-app@latest

在安裝時，您會看到以下提示

終端機
What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`?  No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*

在提示之後，create-next-app 將會建立一個以您的專案名稱命名的資料夾，並安裝所需的依賴套件。

手動安裝

要手動建立新的 Next.js 應用程式，請安裝所需的套件

終端機
npm install next@latest react@latest react-dom@latest

開啟您的 package.json 檔案並新增以下 scripts

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

這些指令碼指的是應用程式開發的不同階段

  • dev：執行 next dev 以在開發模式下啟動 Next.js。
  • build：執行 next build 以建置用於生產環境的應用程式。
  • start：執行 next start 以啟動 Next.js 生產伺服器。
  • lint：執行 next lint 以設定 Next.js 內建的 ESLint 配置。

建立 app 目錄

Next.js 使用檔案系統路由，這表示您應用程式中的路由取決於您如何組織檔案結構。

建立一個 app 資料夾，然後新增 layout.tsx 和 page.tsx 檔案。當使用者訪問您應用程式的根目錄 (/) 時，將會渲染這些檔案。

App Folder Structure

在 app/layout.tsx 內建立一個根版面配置，其中包含必要的 <html> 和 <body> 標籤

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

最後，建立一個首頁 app/page.tsx，其中包含一些初始內容

app/page.tsx
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

小提示:

  • 如果您忘記建立 layout.tsx，Next.js 將在執行開發伺服器 next dev 時自動建立此檔案。
  • 您可以選擇性地在專案根目錄中使用 src 目錄，以將應用程式的程式碼與設定檔分開。

建立 public 資料夾 (選用)

您可以選擇性地在專案根目錄建立一個 public 資料夾，以儲存靜態資源，例如圖片、字體等。然後，可以從根 URL (/) 開始，從您的程式碼引用 public 內的檔案。

執行開發伺服器

  1. 執行 npm run dev 以啟動開發伺服器。
  2. 訪問 https://127.0.0.1:3000 以檢視您的應用程式。
  3. 編輯 app/page.tsx檔案並儲存它，以在瀏覽器中查看更新後的結果。

設定 TypeScript

最低 TypeScript 版本：v4.5.2

Next.js 內建 TypeScript 支援。要將 TypeScript 新增至您的專案，請將檔案重新命名為 .ts / .tsx。執行 next dev，Next.js 將自動安裝必要的依賴套件，並新增一個包含建議配置選項的 tsconfig.json 檔案。

IDE 外掛程式

Next.js 包含一個自訂的 TypeScript 外掛程式和類型檢查器，VSCode 和其他程式碼編輯器可以使用它們進行進階的類型檢查和自動完成。

您可以在 VS Code 中啟用此外掛程式，方法是

  1. 開啟命令面板 (Ctrl/⌘ + Shift + P)
  2. 搜尋 "TypeScript: Select TypeScript Version"
  3. 選擇 "Use Workspace Version"
TypeScript Command Palette

現在，當編輯檔案時，將會啟用自訂外掛程式。當執行 next build 時，將會使用自訂類型檢查器。

請參閱 TypeScript 配置 頁面，以取得有關如何在您的專案中使用 TypeScript 的更多資訊。

設定 ESLint

Next.js 內建 ESLint，當您使用 create-next-app 建立新專案時，會自動安裝必要的套件並配置適當的設定。

要將 ESLint 新增到現有專案，請將 next lint 作為指令碼新增到 package.json

package.json
{
  "scripts": {
    "lint": "next lint"
  }
}

然後，執行 npm run lint，系統將引導您完成安裝和配置過程。

終端機
npm run lint

您會看到像這樣的提示

? 您想要如何配置 ESLint？

❯ 嚴格 (建議)
基本
取消

  • 嚴格：包含 Next.js 的基本 ESLint 配置以及更嚴格的核心網頁指標規則集。這是首次設定 ESLint 的開發人員的建議配置。
  • 基本：包含 Next.js 的基本 ESLint 配置。
  • 取消：不包含任何 ESLint 配置。如果您計劃設定自己的自訂 ESLint 配置，才選擇此選項。

如果選擇了這兩個配置選項中的任何一個，Next.js 將自動在您的應用程式中安裝 eslint 和 eslint-config-next 作為依賴項，並在您的專案根目錄中建立一個 .eslintrc.json 檔案，其中包含您選擇的配置。

您現在可以每次想要執行 ESLint 以捕捉錯誤時執行 next lint。一旦設定了 ESLint，它也會在每次建置期間 (next build) 自動執行。錯誤會導致建置失敗，而警告則不會。

請參閱 ESLint 外掛程式 頁面，以取得有關如何在您的專案中配置 ESLint 的更多資訊。

設定絕對路徑匯入和模組路徑別名

Next.js 內建支援 tsconfig.json 和 jsconfig.json 檔案的 "paths" 和 "baseUrl" 選項。這些選項可讓您將專案目錄別名為絕對路徑，從而更輕鬆地匯入模組。例如

// Before
import { Button } from '../../../components/button'
 
// After
import { Button } from '@/components/button'

要配置絕對路徑匯入，請將 baseUrl 配置選項新增至您的 tsconfig.json 或 jsconfig.json 檔案。例如

tsconfig.json 或 jsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

除了配置 baseUrl 路徑之外，您還可以使用 "paths" 選項來 "alias" 模組路徑。

例如，以下配置將 @/components/* 映射到 components/*

tsconfig.json 或 jsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

每個 "paths" 都相對於 baseUrl 位置。例如

src/app/page.tsx
import Button from '@/components/button'
import '@/styles/styles.css'
 
export default function HomePage() {
  return (
    <div>
      <h1>Hello World</h1>
      <Button />
    </div>
  )
}