开发环境搭建与工程脚手架

# macOS / Linux 安装 fnm
curl -fsSL https://fnm.vercel.app/install | bash
 
# Windows（通过 winget）
winget install Schniz.fnm
 
# 安装并使用 Node.js 20 LTS
fnm install 20
fnm use 20
fnm default 20
 
# 验证
node -v  # v20.x.x
npm -v   # 10.x.x

echo "20" > .node-version

# 通过 corepack 启用（Node.js 内置）
corepack enable
corepack prepare pnpm@latest --activate
 
# 验证
pnpm -v  # 9.x.x

{
  "packageManager": "[email protected]",
  "engines": {
    "node": ">=20.0.0"
  }
}

// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "prisma.prisma",
    "ms-vscode.vscode-typescript-next",
    "formulahendry.auto-rename-tag"
  ]
}

// .vscode/settings.json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

pnpm create next-app@latest ai-saas-platform
 
# 交互式选项（推荐选择）
✔ Would you like to use TypeScript?              → Yes
✔ Would you like to use ESLint?                  → Yes
✔ Would you like to use Tailwind CSS?            → Yes
✔ Would you like your code inside a `src/` directory? → No
✔ Would you like to use App Router?              → Yes
✔ Would you like to use Turbopack for next dev?  → Yes (Next.js 16 默认)
✔ Would you like to customize the import alias?  → Yes → @/*

cd ai-saas-platform
pnpm dev
 
# 输出
  ▲ Next.js 16.x.x
  - Local:    http://localhost:3000
  - Network:  http://192.168.x.x:3000
  - Turbopack: enabled
 
 ✓ Starting...
 ✓ Ready in 1.2s

# 安装依赖
pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-config-next

// eslint.config.mjs
import { dirname } from 'path'
import { fileURLToPath } from 'url'
import { FlatCompat } from '@eslint/eslintrc'
import js from '@eslint/js'
 
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
 
const compat = new FlatCompat({
  baseDirectory: __dirname,
})
 
export default [
  js.configs.recommended,
  ...compat.extends('next/core-web-vitals', 'next/typescript'),
  {
    rules: {
      '@typescript-eslint/no-unused-vars': ['warn', {
        argsIgnorePattern: '^_',
        varsIgnorePattern: '^_',
      }],
      'react/no-unescaped-entities': 'off',
      '@next/next/no-img-element': 'off',
    },
  },
]

pnpm add -D prettier prettier-plugin-tailwindcss

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "plugins": ["prettier-plugin-tailwindcss"]
}

pnpm add -D husky lint-staged
pnpm exec husky init

// package.json 中添加
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

# .husky/pre-commit
pnpm exec lint-staged

# .env.local
# 🔒 服务端专用（不会暴露给浏览器）
DATABASE_URL="postgresql://user:pass@localhost:5432/ai_saas"
OPENAI_API_KEY="sk-..."
STRIPE_SECRET_KEY="sk_test_..."
AUTH_SECRET="your-auth-secret"
 
# 🌐 客户端可用（会暴露给浏览器）
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_POSTHOG_KEY="phc_..."

pnpm add @t3-oss/env-nextjs zod

// lib/env.ts
import { createEnv } from '@t3-oss/env-nextjs'
import { z } from 'zod'
 
export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    OPENAI_API_KEY: z.string().startsWith('sk-'),
    STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
    AUTH_SECRET: z.string().min(32),
    RESEND_API_KEY: z.string(),
    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
    NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    AUTH_SECRET: process.env.AUTH_SECRET,
    RESEND_API_KEY: process.env.RESEND_API_KEY,
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
  },
})

import { env } from '@/lib/env'
 
// ✅ 类型安全
env.DATABASE_URL     // string（保证是有效 URL）
env.OPENAI_API_KEY   // string（保证以 sk- 开头）
 
// ❌ 编译报错：client 环境变量不能在服务端反过来用
// env.NEXT_PUBLIC_APP_URL  // 在客户端组件中可用

# .env.example（提交到 Git，作为团队参考）
# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/ai_saas"
 
# Auth
AUTH_SECRET="generate-with-openssl-rand-base64-32"
 
# AI
OPENAI_API_KEY="sk-..."
 
# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
 
# Email
RESEND_API_KEY="re_..."
 
# Public
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_POSTHOG_KEY=""

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // React Compiler（实验性，推荐开启）
  experimental: {
    reactCompiler: true,
  },
 
  // 图片域名白名单
  images: {
    remotePatterns: [
      { hostname: 'avatars.githubusercontent.com' },
      { hostname: '*.amazonaws.com' },
      { hostname: '*.cloudflare.com' },
    ],
  },
 
  // 独立部署模式（Docker 部署需要）
  output: 'standalone',
 
  // 重定向
  async redirects() {
    return [
      {
        source: '/app',
        destination: '/chat',
        permanent: true,
      },
    ]
  },
}
 
export default nextConfig

# 初始化 Git
git init
git add .
git commit -m "feat: initial Next.js 16 project setup
 
- Next.js 16 with App Router and Turbopack
- TypeScript strict mode
- Tailwind CSS v4 + PostCSS
- ESLint Flat Config + Prettier
- Husky + lint-staged
- Type-safe environment variables (@t3-oss/env-nextjs)
- Production-ready directory structure"