建立新的 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"
  }
}

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

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

建立 `pages` 目錄

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

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

pages/index.tsx

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

接下來，在 pages/ 內新增一個 _app.tsx 檔案以定義全域版面配置。深入瞭解自訂 App 檔案。

pages/_app.tsx

import type { AppProps } from 'next/app'
 
export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

最後，在 pages/ 內新增一個 _document.tsx 檔案以控制來自伺服器的初始回應。深入瞭解自訂 Document 檔案。

pages/_document.tsx

import { Html, Head, Main, NextScript } from 'next/document'
 
export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

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

您可以選擇性地在專案根目錄建立一個 public 資料夾，以存放靜態資源，例如圖片、字型等。public 內的檔案接著可以從基礎 URL (/) 開始被您的程式碼參照。

執行開發伺服器

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

設定 TypeScript

最低 TypeScript 版本：v4.5.2

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

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

設定 ESLint

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

若要將 ESLint 新增至現有專案，請將 next lint 作為 script 新增至 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 Plugin 頁面，以取得更多關於如何在您的專案中配置 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" 選項來「別名化」模組路徑。

例如，以下配置將 @/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>
  )
}