Next.js 配置指南

学习如何使用 package.json、next.config.ts、TypeScript 和环境变量配置 Next.js 项目，实现最佳开发和生产环境。

在了解 NextDevKit 的代码结构后，本节你将学习核心的 Next.js 项目配置文件，并且快速上手 NextDevKit 已有的配置。

Next.js 配置文件

Next.js 配置涉及几个关键文件，它们控制应用程序的构建、运行和部署方式。理解每个配置文件确保获得最佳的开发和生产性能。

package.json

package.json 是任何 Next.js 项目的核心配置文件，定义项目元数据、依赖项和可执行脚本。

基本项目信息

你可以首先修改项目名称和描述，例如：

package.json

{
  "name": "nextdevkit",
  "version": "1.0.0",
  "description": "next.js template with authentication, payment, and more",
  "packageManager": "pnpm@10.10.0"
}

核心脚本命令

NextDevKit 提供了完整的开发和构建脚本集，你可以根据你的需求修改这些脚本：

package.json

{
  "scripts": {
    // 开发相关
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    
    // 代码质量
    "lint": "biome check --write .",
    "lint:fix": "biome check --fix --unsafe .",
    "format": "biome format --write .",
    
    // 数据库操作
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    
    // 针对 cloudflare workers 和 AWS 等平台的专门命令，在特定的模板中存在
    "build:prod": "pnpm run opennext:build && wrangler deploy --dry-run --outdir=dist",
    "deploy": "pnpm run opennext:build && opennextjs-cloudflare deploy",
  }
}

next.config.ts

除了修改 package.json 文件外，你还可以修改 next.config.ts 文件配置 Next.js 构建和运行时行为。

NextDevKit 默认包含现代 Web 应用程序的优化设置，你可以根据你的需求修改这些配置。

基本配置结构

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // 配置选项
};

export default nextConfig;

基本配置选项

当前 NextDevKit 的配置：

next.config.ts

import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";

const withMDX = createMDX();

const nextConfig: NextConfig = {
	// output: "standalone",
	images: {
		remotePatterns: [
			{
				hostname: "**",
			},
		],
	},
};

const withNextIntl = createNextIntlPlugin();

export default withMDX(withNextIntl(nextConfig));

容器化配置：

如果你需要将你的 Next.js 项目部署到容器化环境中，例如 AWS ECS、Railway, Fly.io 等，你可以使用 output: "standalone" 配置。

next.config.ts


const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

图片配置：

如果你需要修改图片的认证域名，可以修改 images.remotePatterns 配置。当前模板配置为 **，代表所有域名。仅仅为了大家 Vibe Coding 方便，所以没有限制。如果你有安全相关的需求，请修改为你的域名。

更多配置信息可以访问 Next.js 图片配置文档。

next.config.ts

const nextConfig: NextConfig = {
  images: {
    // 外部图片域名
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com'
      },
      {
        protocol: 'https',
        hostname: 'avatars.githubusercontent.com'
      }
    ],
  }
};

需要注意的一些配置：

Vercel 平台中的 Next.js 的图片优化可能会导致高昂的 Image Optimization 费用，所以如果担心费用问题，可以关闭图片优化。

next.config.ts

const nextConfig: NextConfig = {
  // 关闭 Image Optimization 的自动优化
  images: {
    unoptimized: true,
  },
};

TypeScript 配置

最后，你可以根据你的需求修改 TypeScript 配置，确保类型安全和最佳开发体验。

NextDevKit TypeScript 配置

下面是 NextDevKit 的 TypeScript 配置，你可以根据你的需求修改这些配置。

tsconfig.json

{
	"compilerOptions": {
		"target": "ES2017",
		"lib": ["dom", "dom.iterable", "esnext"],
		"allowJs": true,
		"skipLibCheck": true,
		"strict": false,
		"noEmit": true,
		"incremental": true,
		"module": "esnext",
		"esModuleInterop": true,
		"moduleResolution": "bundler",
		"resolveJsonModule": true,
		"isolatedModules": true,
		"jsx": "preserve",
		"plugins": [
			{
				"name": "next"
			}
		],
		"paths": {
			"@/*": ["./src/*"],
			"@/public/*": ["./public/*"],
			"@/source": ["./.source"]
		}
	},
	"include": ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
	"exclude": ["node_modules"]
}

大多数情况，你只需要更改 compilerOptions 中的 paths 配置，来配置你的项目路径映射。

路径映射的好处

使用路径映射

// 之前（相对导入）
import Button from '../../../components/ui/button';
import { auth } from '../../../../lib/auth/client';

// 之后（带路径映射的绝对导入）
import Button from '@/components/ui/button';
import { auth } from '@/lib/auth/client';

环境变量

在学会所有的 Next.js 配置后，最后我们学习一下环境变量配置。

如果你需要在本地配置不同环境的环境变量，可以使用下面的命名方式配置不同部署环境中的应用程序行为。

注意所有的环境变量文件都不建议提交到 git 仓库中。

环境文件结构

.env.xxx

.env                # 本地开发
.env.production     # 生产环境
.env.example        # 模板文件（提交到仓库）

在本地你运行不同部署或者启动的命令时，会自动读取对应的环境变量文件。

例如本地开发的话，你执行 pnpm dev 会自动读取 .env 文件中的环境变量。

假如你需要在本地通过命令行的方式部署到云环境，例如 cloudflare 和 AWS，你在本地执行 pnpm run deploy 会自动读取 .env.production 文件中的环境变量。

本地开发

如果你要启动一个最少功能的 NextDevKit 项目，你需要在 .env 文件中配置以下环境变量：

变量	描述	示例	必需
`BETTER_AUTH_SECRET`	Better Auth 会话加密的密钥	`your-32-character-secret-key`	✅
`BETTER_AUTH_URL`	应用程序的基础URL	`http://localhost:3000`	✅
`NEXT_PUBLIC_APP_URL`	客户端使用的公共URL	`http://localhost:3000`	✅
`DATABASE_URL`	数据库URL	`postgresql://localhost:5432/xxxx`	✅

BETTER_AUTH_SECRET 是一个随机字符串，用于加密和生成哈希值，你可以使用以下命令生成一个 32 位安全的密钥：

# 执行命令生成一个 32 位安全的密钥
openssl rand -base64 32

如果你使用 Cloudflare workers 模板，你可以不设置 DATABASE_URL，因为可以使用内置的 SQLite 数据库。

如果你使用的是 Next.js 模板，你需要配置 DATABASE_URL 来连接你的数据库。你可以选择 Neon 或者 Supabase 等数据库服务。可以参考 PostgreSQL 数据库配置中的配置。

设置完成最少的环境变量配置后，你就可以在本地启动你的 NextDevKit 项目了。

pnpm dev

访问浏览器 http://localhost:3000 ，你应该可以看到一个默认的 landing page 页面。

On this page