Next.js 混合渲染工程栈

基于 Next.js App Router、Tailwind CSS v4 与 SSP UI Registry 搭建可复用的企业级前端栈

为什么选择这一栈

这套工程栈旨在充分利用 Next.js 的混合渲染能力(支持 Server Components、静态生成与增量更新),同时复用 SSP UI Registry 的组件与工具,快速构建具备国际化、主题切换、稳定数据访问层的产品级应用。

首次出现的缩写会在括号内说明,便于团队成员快速对齐:

  • RSC(React Server Components):在服务器执行的 React 组件,可减少客户端 bundle 大小并隐藏敏感逻辑。
  • BFF(Backend for Frontend):面向前端定制的数据接口层,可通过 Next.js Route Handlers 实现。

栈组成概览

能力推荐工具作用
框架Next.js 15 App Router支持 RSC、Route Handlers、App Router 目录约定
样式体系Tailwind CSS v4 + SSP Theme下载 ssp-style.json 后自动增量更新 app/globals.css
UI 组件符合 shadcn Registry 规范的能力(shadcn/ui、本 Registry、21st.dev 等)复用基础组件与 Block,保持视觉一致性
多主题next-themes实现明暗主题与自定义主题切换
国际化next-intlApp Router 的局部与全局翻译方案
数据访问make-api-request + use-cancelable-swr构建类型安全、可中断的请求层(数据访问层而非严格 MVC)
状态管理zustand轻量的全局状态存储,与 Server Components 友好
类型/校验zodSchema 校验 + TypeScript 类型推导
动效motion(Framer Motion 官方包)Page Transition、组件动效
质量保障@biomejs/biome同时作为 Linter 与 Formatter,统一团队规范

项目初始化与依赖

  • 按照 Next.js 官方 App Router 指南 创建项目,并开启 TypeScript、ESLint、Tailwind 支持。
  • Tailwind CSS v4 默认通过 app/globals.css(或 src/app/globals.css)维护主题与 Design Token,无需再维护 tailwind.config.ts 配置文件。
  • 依赖安装遵循组织的包管理策略,建议通过 Registry CLI 下载能力(Theme、UI、Hook、Item),避免在文档中硬编码包版本。

样式与主题整合(SSP Theme)

  1. 在本站点下载 ssp-style.json,执行后将自动增量更新 app/globals.css
  2. 如需扩展 Design Token,可复制 Registry style.json 中的变量到 globals.css@theme 块,并结合 next-themes 控制暗色模式。

UI 与 Block 组件实践

  • 选择符合 shadcn Registry 规范的组件能力(例如 shadcn/ui 官方套件、21st.dev 或本 Registry),通过 CLI 或 RegistryDownload 引入。
  • 建议建立 components/registry.ts 聚合导出常用组件,方便在 Server Components 与 Client Components 中复用。

国际化(next-intl)

  • 参考 next-intl 官方文档 配置多语言路由与翻译 Hook。Next.js 16 之后不再需要 middleware.ts,可直接利用 App Router Layout 实现语言前缀与信息注入。

数据访问层:make-api-request + use-cancelable-swr

这两个 Registry 能力组合构成前端的数据访问层。详细文档参阅 Make API Request Item

lib/http/product.ts
import { makeApiRequest } from "@/registry/ssp/item/make-api-request/base"
import { ProductApi } from "@/registry/ssp/item/make-api-request/example/index.template"

export const fetchProducts = () => makeApiRequest(ProductApi.getProducts)
app/(dashboard)/products/page.tsx
import { useCancelableSwr } from "@/registry/ssp/hook/use-cancelable-swr"
import { fetchProducts } from "@/lib/http/product"

export default function ProductsPage() {
  const [{ data, isLoading, error }] = useCancelableSwr(
    { key: ["products"], url: "/api/products" },
    { method: "GET", fetcher: fetchProducts }
  )

  if (isLoading) return <p>Loading…</p>
  if (error) return <p>Failed to load</p>
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

状态管理与动效

  • zustand:参阅 Zustand Item 文档,在 lib/stores 中维护轻量状态,按需启用中间件(persistimmer 等)。
  • motion:用于 Page Transition 或交互动画,可在公共布局中统一定义 MotionLayout,在 Block 内共享动效变量。

Schema 校验与类型推导

  • 使用 zod 定义 Schema,并与 make-api-request 结合生成请求/响应类型。
  • Schema 可同时用于表单验证、服务端数据校验与客户端推断,减少类型重复书写。

工程化与质量保障

  • 使用 @biomejs/biome 统一格式化与 Lint,具体规则与示例参见 Biome Item 文档
  • 建议在 CI/CD 中强制执行 bun run lintbun run format,保持仓库内代码风格一致。

部署与运维建议

  1. 托管平台:参考 Next.js 官方部署指南,在 Vercel、Netlify、Cloudflare Pages 等提供商上部署。确认 Edge Region、环境变量与日志配置满足业务需求。
  2. 容器化(Dockerize):如需自托管,可参考下方 Dockerfile 示例将 Next.js 应用打包部署至 Kubernetes 或传统主机。强调:请务必在 next.config.js 中开启 output: "standalone",确保容器镜像仅包含所需文件,并适用于任意 Node 24+ 或 Bun 运行时环境。具体容器化流程与最佳实践可结合团队 Registry Item 或自有模板扩展完善。
Dockerfile
# syntax=docker/dockerfile:1

FROM node:24-alpine AS base

# Bun 安装需要的工具
RUN apk add --no-cache bash curl xz ca-certificates git
# 安装 Bun(可通过 --build-arg 指定版本,否则装最新)
ARG BUN_VERSION=
ENV BUN_INSTALL=/usr/local/bun
RUN bash -lc 'set -eux; v="${BUN_VERSION:+bun-v${BUN_VERSION}}"; curl -fsSL https://bun.com/install | bash -s -- ${v:-}'
# 让后续阶段都能找到 bun
ENV PATH="${BUN_INSTALL}/bin:${PATH}"
# 验证
RUN bun --version && node -v && npm -v

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* bun.lock* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  elif [ -f bun.lock ]; then bun i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
ENV NEXT_TELEMETRY_DISABLED=1

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  elif [ -f bun.lock ]; then bun run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
# Uncomment the following line in case you want to disable telemetry during runtime.
ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/config/next-config-js/output
ENV HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]

Checklist

  • 已应用 SSP Theme 并验证明暗主题切换。
  • 常用 UI、Block、Hook、Item 能力已通过 Registry 引入。
  • make-api-request + use-cancelable-swr 建立标准数据访问层。
  • 国际化策略(如 next-intl)已完成配置并通过官方示例验证。
  • Biome 和 Zod 校验纳入 CI/CD 流程。
  • Page Transition、重点交互已使用 motion 定义动效。
  • 目标平台部署验证通过,并评估容器化部署方案。

完成以上步骤后,即可获得一套可扩展、类型安全、具备国际化及主题切换能力的 Next.js 工程栈,为后续的业务模块开发提供稳固基座。