1

node --version

1
2
3
4
5
6
7

# 使用 nvm 安装 Node.js 18（如果你已经安装了 nvm）
nvm install 18
nvm use 18

# 检查版本，确认升级成功
node --version  # 输出：v18.17.0 或更高版本
npm --version   # 检查 npm 版本（通常是随 Node.js 一起安装的）

1
2
3
4
5

# 查看当前使用的 create-next-app 版本
npx create-next-app --version

# 查看当前项目的 Next.js 版本
cat package.json | grep next

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 使用最新的稳定版（默认行为）
npx create-next-app@latest my-project

# 指定 Next.js 14.x 版本
npx create-next-app@14 my-project

# 指定 Next.js 13.x 版本
npx create-next-app@13 my-project

# 使用 canary 版本（最新开发版，可能不稳定）
npx create-next-app@canary my-project

# 指定具体版本号
npx create-next-app@14.0.0 my-project

1
2
3
4
5

# 如果你想指定具体的小版本号（比如你想复现一个 14.0.0 的 bug）
npx create-next-app@14.0.0 my-bug-reproduction-project

# 如果你想用 Next.js 15 的 canary 版本来尝鲜
npx create-next-app@canary my-next15-preview

1
2
3
4
5
6
7
8

# 使用 npm（默认）
npx create-next-app my-project --use-npm

# 使用 yarn
npx create-next-app my-project --use-yarn

# 使用 pnpm
npx create-next-app my-project --use-pnpm

1
2
3
4
5
6
7
8
9

# 检查你当前的包管理器版本
npm --version   # npm 的版本
yarn --version  # yarn 的版本
pnpm --version  # pnpm 的版本

# 如果你想切换包管理器，建议先删除 node_modules 和锁文件，然后重新安装
rm -rf node_modules package-lock.json  # npm 的锁文件
rm -rf node_modules yarn.lock         # yarn 的锁文件
rm -rf node_modules pnpm-lock.yaml    # pnpm 的锁文件

1

Error: Target directory is not empty. Please specify an empty directory or use the --force flag.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 方案一：换一个空的目录名
npx create-next-app my-fresh-project

# 方案二：先删除已有目录，然后重新创建
rm -rf my-project
npx create-next-app my-project

# 方案三：手动清空目录中的文件（更安全的做法）
cd my-project
rm -rf *  # 删除目录内所有文件（但保留目录本身）
npx create-next-app .  # 在当前空目录创建项目

1
2

npm ERR! network ETIMEDOUT 104.16.17.35:443
npm ERR! network This is a problem related to network connectivity.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 设置淘宝镜像（推荐，速度快，稳定性好）
npm config set registry https://registry.npmmirror.com

# 验证设置是否成功
npm config get registry
# 输出：https://registry.npmmirror.com

# 注意：create-next-app 不支持 --registry 参数
# 如果 npm 安装缓慢，请先执行上面的 npm config set registry
# 然后再运行 create-next-app

1
2
3
4
5

# yarn 配置镜像源
yarn config set registry https://registry.npmmirror.com

# pnpm 配置镜像源
pnpm config set registry https://registry.npmmirror.com

1

Error: ENOSPC: no space left on device, write

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 首先检查磁盘空间
df -h  # Linux/macOS
# 或
wmic logicaldisk get size,freespace,caption  # Windows

# 清理 npm/yarn/pnpm 的缓存
npm cache clean --force
yarn cache clean
pnpm store prune

# 删除不需要的大文件，比如：
# - node_modules（如果之前有安装过其他项目）
# - 各种临时文件
# - 旧的下载文件

1

npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 方案一：使用 sudo 提升权限（不推荐长期使用）
sudo npx create-next-app my-project

# 方案二：配置 npm 的全局目录到用户目录（推荐）
mkdir ~/.npm-global  # 创建一个用户目录用于存放全局包
npm config set prefix '~/.npm-global'  # 设置 npm 的全局目录

# 将路径添加到 PATH 环境变量（编辑 ~/.bashrc 或 ~/.zshrc）
export PATH=~/.npm-global/bin:$PATH

# 使配置生效
source ~/.bashrc  # 如果你使用的是 bash
# 或
source ~/.zshrc   # 如果你使用的是 zsh

# 方案三：在 WSL 中，确保 Windows 磁盘挂载的目录有正确权限
# WSL 访问 Windows 磁盘文件时，可能会有权限问题
# 建议在 WSL 的本地文件系统中创建项目，而不是在 /mnt/c/ 下
cd ~  # 切换到 WSL 的主目录
mkdir projects
cd projects
npx create-next-app my-project

1
2
3
4
5

# Windows 风格路径
C:\Users\longx\Projects\my-app

# Unix 风格路径
/home/longx/projects/my-app

1
2
3
4
5
6
7
8

# 在 PowerShell 中创建项目（确保使用 PowerShell 7+）
npx create-next-app my-project

# 使用 WSL2（推荐）
# 首先打开 WSL2 终端
wsl  # 进入默认的 WSL 发行版
cd ~/projects  # 进入 Linux 主目录
npx create-next-app my-project  # 创建项目

1
2
3
4
5

# 在 WSL2 中，你还可以访问 Windows 的磁盘
cd /mnt/c/Users/longx/Projects  # 访问 Windows 的用户目录
# 但是，建议还是在 WSL2 的本地目录下工作，这样速度更快
cd ~/projects
npx create-next-app my-project

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 进入项目目录
cd my-project

# 初始化 Git 仓库（这会创建一个 .git 目录，用于存储版本信息）
git init

# 查看当前状态
git status
# 输出：
# On branch main
# No commits yet
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#   .eslintrc.json
#   .gitignore
#   .next/
#   package-lock.json
#   package.json
#   ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 查看 .gitignore 文件的内容
cat .gitignore

# 输出示例：
# dependencies
# /node_modules
# /.pnp
# .pnp.js

# testing
# /coverage

# Next.js
# /.next/
# /out/

# production
# /build

# misc
# .DS_Store
# *.pem

# debug
# npm-debug.log*
# yarn-debug.log*
# yarn-error.log*

# local env files
# .env*.local
# .env

# vercel
# .vercel

# typescript
# *.tsbuildinfo
# next-env.d.ts

1
2

# 查看 package.json 文件的内容
cat package.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "name": "my-project",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "14.2.5",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "eslint": "^8",
    "eslint-config-next": "14.2.5",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "typescript": "^5"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 进入项目目录
cd my-project

# 安装依赖
npm install
# 输出示例：
# added 312 packages in 5s
# 245 packages are looking for funding
#   run `npm fund` for details

# 启动开发服务器
npm run dev
# 输出示例：
#   ▲ Next.js 14.2.5
#   - Local:        http://localhost:3000
#   - Ready in  1.2s

1
2
3
4
5
6

# 如果你想使用其他端口，可以这样：
npm run dev -- --port 3005
# 输出：
#   ▲ Next.js 14.2.5
#   - Local:        http://localhost:3005
#   - Ready in  1.2s

1
2
3
4

# 使用 App Router（默认方式）
npx create-next-app my-app-router-project --app
# 或者不指定，因为 App Router 已经是默认选项
npx create-next-app my-project

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

my-project/
├── app/
│   ├── layout.tsx          # 根布局（所有页面共享）
│   ├── page.tsx           # 首页（/）
│   ├── about/
│   │   └── page.tsx       # 关于页（/about）
│   ├── blog/
│   │   ├── page.tsx       # 博客列表（/blog）
│   │   └── [slug]/
│   │       └── page.tsx   # 博客详情（/blog/:slug）
│   └── globals.css        # 全局样式
├── public/                 # 静态资源
└── package.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// app/layout.tsx
// 这是根布局，所有页面都会包裹在这个布局里
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh-CN">
      <body>
        {/* 这里是全局导航栏，所有页面都会显示 */}
        <header>
          <nav>
            <a href="/">首页</a>
            <a href="/about">关于</a>
            <a href="/blog">博客</a>
          </nav>
        </header>

        {/* children 是当前页面的内容 */}
        <main>{children}</main>

        {/* 这里是全局页脚 */}
        <footer>© 2026 我的博客</footer>
      </body>
    </html>
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// app/page.tsx
// 这是首页
export default function HomePage() {
  return (
    <div>
      <h1>欢迎来到我的网站！</h1>
      <p>这是一个使用 App Router 的 Next.js 项目。</p>
    </div>
  )
}

1
2

# 显式指定使用 Pages Router
npx create-next-app my-pages-router-project --no-app

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

my-project/
├── pages/
│   ├── _app.tsx           # 全局 App 组件（所有页面共享）
│   ├── _document.tsx      # 文档组件（自定义 HTML 结构）
│   ├── index.tsx          # 首页（/）
│   ├── about.tsx          # 关于页（/about）
│   ├── blog/
│   │   ├── index.tsx      # 博客列表（/blog）
│   │   └── [id].tsx       # 博客详情（/blog/:id）
│   └── api/
│       └── hello.ts       # API 路由（/api/hello）
├── public/                # 静态资源
└── package.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// pages/_app.tsx
// 这是全局 App 组件，所有页面都会包裹在这个组件里
import type { AppProps } from 'next/app'
import '../styles/globals.css'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      {/* 这里是全局导航栏 */}
      <header>
        <nav>
          <a href="/">首页</a>
          <a href="/about">关于</a>
          <a href="/blog">博客</a>
        </nav>
      </header>

      {/* Component 是当前页面的组件，pageProps 是页面传递过来的数据 */}
      <Component {...pageProps} />

      {/* 这里是全局页脚 */}
      <footer>© 2026 我的博客</footer>
    </>
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// pages/index.tsx
// 这是首页
import type { NextPage } from 'next'

const HomePage: NextPage = () => {
  return (
    <div>
      <h1>欢迎来到我的网站！</h1>
      <p>这是一个使用 Pages Router 的 Next.js 项目。</p>
    </div>
  )
}

export default HomePage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

my-project/
├── src/                    # 源代码目录（所有的应用代码都放在这里）
│   ├── app/                # App Router 的页面文件
│   │   ├── page.tsx
│   │   └── layout.tsx
│   └── components/         # 组件目录（放置可复用的 React 组件）
│       └── Header.tsx
├── public/                 # 静态资源（图片、字体等）
├── package.json
└── ...

1
2
3
4
5
6
7
8
9

my-project/
├── app/                    # App Router 的页面文件（直接在根目录下）
│   ├── page.tsx
│   └── layout.tsx
├── components/             # 组件目录
│   └── Header.tsx
├── public/                 # 静态资源
├── package.json
└── ...

1
2
3
4
5

# 使用 --src-dir 参数
npx create-next-app my-src-project --src-dir

# 不使用 --src-dir 参数（默认）
npx create-next-app my-flat-project

1
2
3
4
5
6
7
8
9

// tsconfig.json 配置绝对路径别名
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]  // 这样 @/components/Button 就等同于 ./src/components/Button
    }
  }
}

1
2
3
4

# 在项目根目录下创建 .env.local 文件
touch .env.local

# 编辑 .env.local 文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# .env.local 文件示例

# 数据库配置
DATABASE_URL=postgres://user:password@localhost:5432/mydb

# API 密钥（敏感信息！）
API_SECRET_KEY=sk-1234567890abcdef

# 第三方服务配置
STRIPE_PUBLIC_KEY=pk_test_12345678
STRIPE_SECRET_KEY=sk_test_12345678

# 应用配置
NEXT_PUBLIC_APP_NAME=我的博客
NEXT_PUBLIC_API_URL=http://localhost:3000/api

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// 读取环境变量
const databaseUrl = process.env.DATABASE_URL
const apiSecretKey = process.env.API_SECRET_KEY

// 在 TypeScript 中，如果你想获得更好的类型提示，
// 可以在项目根目录创建一个 env.d.ts 文件（注意：不要修改 next-env.d.ts，它由 Next.js 自动生成）
// env.d.ts 示例：
/*
/// <reference types="next" />
/// <reference types="next/image-types/global" />

declare module '*.env' {
  export const DATABASE_URL: string
  export const API_SECRET_KEY: string
  export const NEXT_PUBLIC_APP_NAME: string
  export const NEXT_PUBLIC_API_URL: string
}
*/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# .env.local

# 这个变量只在服务器端可用，不会暴露给客户端
DATABASE_URL=postgres://user:password@localhost:5432/mydb
API_SECRET_KEY=sk-1234567890abcdef

# 这个变量会被嵌入到客户端 JavaScript 中，可以被任何人看到
NEXT_PUBLIC_APP_NAME=我的博客

# 这个变量也会被嵌入到客户端 JavaScript 中
NEXT_PUBLIC_API_URL=http://localhost:3000/api

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// app/page.tsx
// 这个组件会在客户端和服务器端都运行

export default function HomePage() {
  // ✅ 安全：这是一个服务器端变量，不会暴露给客户端
  const dbUrl = process.env.DATABASE_URL

  // ✅ 安全但要注意：这个变量会被嵌入到客户端代码中
  // 任何人都可以在浏览器开发者工具中看到它的值
  const appName = process.env.NEXT_PUBLIC_APP_NAME

  // ✅ 安全：这也是一个服务器端变量
  const apiSecret = process.env.API_SECRET_KEY

  return (
    <div>
      <h1>欢迎来到 {appName}！</h1>
      {/* dbUrl 和 apiSecret 不会在客户端代码中出现 */}
      {/* 它们只在服务器端的日志或数据库操作中使用 */}
    </div>
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// app/api/hello/route.ts
// 这个文件只在服务器端运行

export async function GET() {
  // ✅ 安全：这是服务器端代码，没有人能在浏览器中看到这些值
  const dbUrl = process.env.DATABASE_URL
  const apiSecret = process.env.API_SECRET_KEY

  // 可以在服务器端安全地使用这些敏感信息
  console.log('数据库连接字符串是：', dbUrl)  // 只会打印在服务器日志中
  console.log('API 密钥是：', apiSecret)  // 只会打印在服务器日志中

  return Response.json({ message: 'Hello!' })
}

1
2
3

# .gitignore 应该包含这些内容
.env.local
.env.*.local

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# .env.local.example（这是模板，不包含真实值）

# 数据库配置（请替换为你自己的值）
DATABASE_URL=你的数据库连接字符串

# API 密钥（请替换为你自己的值）
API_SECRET_KEY=你的API密钥

# 第三方服务配置
STRIPE_PUBLIC_KEY=你的公开密钥
STRIPE_SECRET_KEY=你的私有密钥

# 应用配置
NEXT_PUBLIC_APP_NAME=你的应用名称
NEXT_PUBLIC_API_URL=你的API地址

1
2
3
4
5
6
7
8
9

# 团队新成员的正确流程：
# 1. 克隆项目
git clone https://github.com/your-org/your-project.git

# 2. 复制模板文件
cp .env.local.example .env.local

# 3. 填写真实值
# 编辑 .env.local 文件，填入自己的配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# .env.local.example

# ===================
# 必填配置
# ===================

# 数据库连接字符串
# 格式：postgres://用户名:密码@主机:端口/数据库名
DATABASE_URL=postgres://user:password@localhost:5432/mydb

# ===================
# 可选配置（有默认值）
# ===================

# 应用的公开名称（前端显示用）
NEXT_PUBLIC_APP_NAME=我的博客

# API 基础地址
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# ===================
# 敏感配置（需要从外部获取）
# ===================

# 第三方支付密钥（请向财务申请）
STRIPE_SECRET_KEY=sk_live_xxxxx

# 发送邮件的服务商 API Key（请向运维申请）
MAILGUN_API_KEY=key-xxxxx

1
2
3
4
5
6
7
8

# ❌ 错误：在生产服务器上运行 dev 命令
npm run dev
# 你的老板/客户/用户：为什么网站这么慢？
# 你：...

# ✅ 正确：先构建，再启动生产服务器
npm run build
npm start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 第一步：构建生产版本
npm run build
# 输出示例：
#   ✓ Compiled successfully
#   ✓ Collecting page data
#   ✓ Generating static pages (for static export)
#   ✓ Build completed successfully
#
#   Output directory: .next
#   ✓ Collect optimizations

1
2
3
4
5
6

# 第二步：启动生产服务器
npm start
# 输出示例：
#   ▲ Next.js 14.2.5
#   - Local:        http://localhost:3000
#   - production   http://your-domain.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 或者使用 Vercel CLI 进行部署
# 首先安装 Vercel CLI
npm install -g vercel

# 登录 Vercel
vercel login

# 进入项目目录并部署
cd my-project
vercel

# 按照提示操作：
# ? Set up and deploy? [Y/n] y
# ? Which scope? your-username
# ? Link to existing project? [y/N] n
# ? What's your project's name? my-project
# ? In which directory is your code located? ./
# ? Want to override the settings? [y/N] n

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Railway CLI 安装
npm install -g @railway/cli

# 登录
railway login

# 部署
cd my-project
railway init
railway up

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Fly.io CLI 安装
curl -L https://fly.io/install.sh | sh

# 登录
fly auth login

# 创建应用
cd my-project
fly launch

# 部署
fly deploy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# Dockerfile（多阶段构建）

# 阶段一：构建
FROM node:18-alpine AS builder
WORKDIR /app

# 复制依赖文件
COPY package*.json ./

# 安装依赖（包括 devDependencies，因为构建需要 TypeScript 等工具）
RUN npm ci

# 复制源代码
COPY . .

# 构建生产版本
RUN npm run build

# 阶段二：运行
FROM node:18-alpine AS runner
WORKDIR /app

# 创建一个非 root 用户（更安全）
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# 复制构建产物
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# 切换到非 root 用户
USER nextjs

# 暴露端口
EXPOSE 3000

# 启动命令
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

1
2
3
4
5
6
7

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',  // 启用 standalone 模式，只打包运行时必需的文件
}

module.exports = nextConfig

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 构建 Docker 镜像
docker build -t my-nextjs-app .

# 运行容器
docker run -p 3000:3000 my-nextjs-app

# 或者使用 docker-compose
# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/mydb
      - API_SECRET_KEY=your-secret-key
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata: