建立新的 Next.js 應用程式

系統需求

開始之前，請確保您的系統符合以下要求：

Node.js 18.18 或更高版本
macOS、Windows（包括 WSL）或 Linux

自動安裝

建立新 Next.js 應用程式最快的方法是使用 create-next-app，它會自動為您設定所有內容。要建立專案，請執行：

終端機

npx create-next-app@latest

安裝過程中，您會看到以下提示：

終端機

您的專案名稱是什麼？ my-app
要使用 TypeScript 嗎？ 否 / 是
要使用 ESLint 嗎？ 否 / 是
要使用 Tailwind CSS 嗎？ 否 / 是
要將程式碼放在 `src/` 目錄中嗎？ 否 / 是
要使用 App Router 嗎？（推薦） 否 / 是
要在 `next dev` 中使用 Turbopack 嗎？ 否 / 是
要自訂導入別名（預設為 `@/*`）嗎？ 否 / 是
您想配置什麼導入別名？ @/*

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

手動安裝

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

終端機

npm install next@latest react@latest react-dom@latest

然後，將以下腳本新增到您的 package.json 檔案中：

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

這些腳本對應應用程式開發的不同階段：

next dev：啟動開發伺服器
next build：為生產環境建置應用程式
next start：啟動生產伺服器
next lint：執行 ESLint

建立 `pages` 目錄

Next.js 使用檔案系統路由，這意味著應用程式中的路由由您如何組織檔案決定。

在專案根目錄建立一個 pages 目錄。然後，在 pages 資料夾內新增一個 index.tsx 檔案。這將是您的首頁（/）：

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

接下來，在 pages/ 內新增一個 _app.tsx 檔案來定義全域佈局。了解更多關於自訂 App 檔案的資訊。

import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

最後，在 pages/ 內新增一個 _document.tsx 檔案來控制伺服器的初始回應。了解更多關於自訂 Document 檔案的資訊。

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

建立 `public` 資料夾（選用）

在專案根目錄建立一個 public 資料夾來儲存靜態資源，例如圖片、字體等。public 內的檔案可以從基礎 URL（/）開始被您的程式碼引用。

然後，您可以使用根路徑（/）引用這些資源。例如，public/profile.png 可以引用為 /profile.png：

import Image from 'next/image'

export default function Page() {
  return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}

執行開發伺服器

執行 npm run dev 啟動開發伺服器
訪問 http://localhost:3000 查看您的應用程式
編輯 pages/index.tsx 檔案並儲存，即可在瀏覽器中看到更新後的結果

設定 TypeScript

最低 TypeScript 版本：v4.5.2

Next.js 內建支援 TypeScript。要將 TypeScript 新增到您的專案中，請將檔案重新命名為 .ts / .tsx 並執行 next dev。Next.js 會自動安裝必要的依賴項並新增一個 tsconfig.json 檔案，其中包含推薦的設定選項。

更多資訊請參閱 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 配置以及更嚴格的 Core Web Vitals 規則集。這是首次設定 ESLint 的開發人員的推薦配置。
基本：包含 Next.js 的基本 ESLint 配置。
取消：跳過配置。如果您計劃設定自己的自訂 ESLint 配置，請選擇此選項。

如果選擇「嚴格」或「基本」，Next.js 會自動在您的應用程式中安裝 eslint 和 eslint-config-next 作為依賴項，並在專案根目錄中建立一個 .eslintrc.json 檔案，其中包含您選擇的配置。

現在，您可以在每次想要執行 ESLint 來捕捉錯誤時執行 next lint。ESLint 設定完成後，它也會在每次建置（next build）時自動執行。錯誤會導致建置失敗，而警告則不會。

更多資訊請參閱 ESLint 插件頁面。

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

Next.js 內建支援 tsconfig.json 和 jsconfig.json 檔案中的 "paths" 和 "baseUrl" 選項。

這些選項允許您將專案目錄別名為絕對路徑，使導入模組更簡單、更清晰。例如：

// 之前
import { Button } from '../../../components/button'

// 之後
import { Button } from '@/components/button'

要配置絕對導入，請將 baseUrl 配置選項新增到您的 tsconfig.json 或 jsconfig.json 檔案中。例如：

tsconfig.json 或 jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

除了配置 baseUrl 路徑外，您還可以使用 "paths" 選項來「別名」模組路徑。

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

tsconfig.json 或 jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

每個 "paths" 都是相對於 baseUrl 位置的。

On this page