官方介绍文章

Ryan Carson 的使用心得

安装 Ralph

手动复制到项目

# 在项目根目录执行
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# 复制适合你 AI 工具的提示词模板：
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # for Amp
# 或
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # for Claude Code

chmod +x scripts/ralph/ralph.sh

通过 Agent Skills 安装

手动复制

# Amp
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

# Claude Code
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

通过 Claude Code 官方插件市场

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

安装完成后会获得两个 skill：

• /prd — 生成产品需求文档（PRD）
• /ralph — 将 PRD 转换为 prd.json 格式

配置 Amp 自动交接

编辑 ~/.config/amp/settings.json：

{
  "amp.experimental.autoHandoff": { "context": 90 }
}

这实现了上下文溢出时的自动交接，使 Ralph 能够处理超出单个上下文窗口容量的大型用户故事。

官方工作流

创建 PRD

使用 PRD 技能生成一份详细的需求文档：

Load the prd skill and create a PRD for [your feature description]

回答 AI 提出的澄清问题。该命令会将输出保存至 tasks/prd-[功能名称].md。

将 PRD 转换为 Ralph 格式

使用 Ralph 工具将 Markdown 格式的 PRD 转换为 JSON 格式：

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

这会生成一个 prd.json 文件，其中包含为自主执行而结构化编排的用户故事。

运行 Ralph

# 使用 Amp（默认）
./scripts/ralph/ralph.sh [max_iterations]

# 使用 Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

默认迭代次数为 10 次。可使用 --tool amp 或 --tool claude 参数选择 AI 编程工具。

Ralph 的执行流程如下：

1. 基于 PRD 中指定的分支名称创建功能分支
2. 选取优先级最高且尚未通过（passes: false）的用户故事
3. 实现该用户故事
4. 运行质量检查（类型检查、测试）
5. 检查通过则进行提交
6. 更新 prd.json，将该故事标记为已通过（passes: true）
7. 将经验总结追加到 progress.txt
8. 重复执行，直至所有故事均通过检查或达到最大迭代次数

核心文件

核心概念

每次迭代 = 全新上下文

每次迭代都会启动一个全新的、上下文干净的 AI 实例（Amp 或 Claude Code）。迭代之间唯一保留的状态包括：

• Git 历史记录（来自之前迭代的提交）
• progress.txt（经验总结与上下文信息）
• prd.json（标记哪些用户故事已完成）

小任务原则

PRD 中的每个需求项都应足够小，确保能在单次上下文窗口内完成。任务过大时，大语言模型会在完成前耗尽上下文，导致生成的代码质量很差。

大小合适的用户故事：

• 添加数据库字段及迁移脚本
• 在现有页面中新增一个 UI 组件
• 为服务端操作新增逻辑并更新
• 为列表添加筛选下拉框

过大的任务（需要拆分）：

• "搭建完整的仪表盘"
• "添加身份认证功能"
• "重构整个 API"

AGENTS.md 更新至关重要

每次迭代完成后，Ralph 都会将经验总结更新到对应的 AGENTS.md 文件中。这一点至关重要——AI 编程工具会自动读取这些文件，后续的迭代以及未来的开发人员都能从总结出的开发模式、注意事项和代码规范中受益。

建议写入 AGENTS.md 的内容：

• 开发模式：例如 "该代码库使用 X 实现 Y 功能"
• 注意事项：例如 "修改 W 时务必同步更新 Z"
• 有用的上下文：例如 "设置面板位于组件 X 中"

反馈循环

Ralph 只有在存在反馈循环的情况下才能正常工作：

• 类型检查捕获类型错误
• 测试验证功能行为
• CI 必须保持通过（损坏的代码会在多次迭代中不断累积问题）

前端故事的浏览器验证

前端用户故事的验收标准中必须包含 "使用 dev-browser 工具在浏览器中验证" 这一项。Ralph 会通过浏览器开发工具访问对应页面、与界面交互，并确认修改功能正常。

停止条件

当所有用户故事的 passes 均为 true 时，Ralph 会输出 <promise>COMPLETE</promise> 并退出循环。

调试

检查当前运行状态：

# 查看哪些故事已完成
cat prd.json | jq '.userStories[] | {id, title, passes}'

# 查看之前迭代的经验记录
cat progress.txt

# 查看 Git 提交历史
git log --oneline -10

归档

启动一个新功能时（使用不同的分支名称），Ralph 会自动归档之前的运行记录。归档文件将保存至 archive/YYYY-MM-DD-feature-name/ 目录下。

安装

# Claude 官方插件市场
/plugin install superpowers@claude-plugins-official

# Superpowers 插件市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# Codex
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

# OpenCode
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

# Gemini
gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

工作流

Superpowers 定义了一套完整的软件工程工作流，将 AI 编码过程分解为多个阶段，每个阶段都有明确的技能/命令、触发条件和产出物。

需求澄清

• 技能/命令： Brainstorming（/brainstorming 或 /superpowers:brainstorming）
• 触发条件： 用户提出新功能或需求指令（如"帮我添加用户登录功能"）
• 输入/输出： 输入为用户自然语言需求；输出为澄清问题问答及初步设计讨论。产物： 需求规格说明文档（文本格式），列出需求要点。
• 注意事项： Skill 会以苏格拉底式提问澄清边界和需求细节（例如支持哪些登录方式、异常处理逻辑等）。必须获得用户确认后才继续下一步。若用户回答有歧义或遗漏，应继续追问；若前后不一致，应重新核对需求。

设计与架构

• 技能： 可视为 Brainstorming 的延续，或隐含在 Plans 中；包含设计审查。
• 触发条件： Brainstorming 确认需求后自动进行。
• 输入/输出： 输入为经过澄清的需求；输出为系统架构或模块划分建议。产物： 系统架构草图或组件列表。
• 注意事项： 设计应符合最佳实践，清晰简洁。若设计方案不足，需回到 Brainstorming 阶段补充需求或重新思考。可利用 Brainstorming 的输出验证设计合理性。

计划拆分

• 技能/命令： Writing Plans（/writing-plans 或 /superpowers:writing-plans）
• 触发条件： 设计方案确认后，输入需求规格开始拆分任务。
• 输入/输出： 输入为需求规格或设计文档；输出为细化的实施步骤。产物： 实施计划文档，列出多个小任务（每个任务包括目标、文件路径、示例代码、验证步骤）。
• 注意事项： 每个任务建议控制在 2–5 分钟内完成。遵循 DRY / YAGNI 原则，仅实现必要功能。若任务粒度过大或过小，应重新调整。执行过程中需持续与用户确认计划。

创建 Git 工作区

• 技能/命令： Using Git Worktrees（隐式执行，无显式命令）
• 触发条件： 实施计划生成后，准备开始编码时自动创建。
• 输入/输出： 在本地项目中执行 Git 命令。产物： 新的开发分支及对应工作目录（如 git worktree add -b <feature> ...）。
• 注意事项： 隔离的开发环境可避免影响主分支。出现严重问题时，可直接删除工作区分支而保持主分支干净。完成后需清理（git worktree remove）以释放资源。

实现与编码

• 技能/命令： Execute Plans（/execute-plan 或 /superpowers:executing-plans），配合测试驱动开发。
• 触发条件： 用户同意执行计划或计划阶段完毕后开始。
• 输入/输出： 输入为任务列表；输出为代码和测试。AI 按计划逐任务实施，每个任务新开会话或子代理进行实现。
• 产物： 功能代码文件、对应测试代码、任务执行日志。
• 注意事项： 强制 TDD 流程：每个功能实现前先生成一个失败测试（红灯），再编写最小代码使其通过（绿灯），最后重构。AI 不会在没有先写失败测试的情况下编写生产代码。若出现较多失败或逻辑混乱，应暂停当前任务进行调试；每次任务完成后及时提交。

测试驱动开发（TDD）

• 技能/命令： Test-Driven Development（/superpowers:test-driven-development）
• 触发条件： 在每个编码任务开始时自动触发。
• 输入/输出： 输入为任务描述；输出为测试用例和实现代码。产物： 单元测试文件与实现文件。
• 注意事项： 遵守「红灯—绿灯—重构」循环。若测试用例编写错误导致无法失败，应重新编写。未通过测试前不得宣称任务完成。AI 会自动回滚错误的先写测试尝试。

系统化调试

• 技能/命令： Systematic Debugging（/superpowers:systematic-debugging）
• 触发条件： 编码过程中遇到未通过的测试、运行时错误或功能异常时主动触发。
• 输入/输出： 输入为错误描述和当前代码上下文；输出为调试分析报告。产物： 四阶段调试记录（根因分析、模式识别、假设测试、修复建议）。
• 注意事项： 必须遵循根因优先原则：先分析问题本质再动手修复。若三次尝试后仍无法解决，应考虑需求或设计层面的问题，必要时回到前面阶段重新审查或寻求人类帮助。记录所有调试假设和结论以备查证。

代码审查

• 技能/命令： Request Code Review（/request-code-review）
• 触发条件： 一个功能分支的所有任务完成、所有测试通过后触发。
• 输入/输出： 输入为当前分支的代码变更；输出为审查报告。产物： 代码审查反馈（优点、缺陷、改进建议）。
• 注意事项： 自动审查会根据代码风格、安全性、性能等规范给出分级问题报告。若发现严重问题（Critical），需修复后重新审查；一般问题可在合并后继续跟进。修复时按建议修改代码并重新运行测试与审查。

合并与发布

• 技能/命令： Finish Branch（合并分支，无显式命令）
• 触发条件： 所有审查问题处理完毕、功能确认无误后执行。
• 输入/输出： 输入为审查完成的分支；输出为合并操作。产物： 合并后的主分支代码。
• 注意事项： 默认先验证所有测试再合并；提供合并/PR、保留或删除选项。合并后应清理 Git 工作树（git worktree remove）以释放空间。合并是正式完成标志，可在此阶段部署或发布版本。

回顾与总结

• 技能： 无特定 Superpowers 技能。
• 触发条件： 合并完成后，可选择性地触发。
• 产物： 项目总结文档（项目经验、遗留问题列表）。
• 注意事项： 建议团队或 AI 总结项目成果与问题，作为未来流程改进的参考。

案例演示

用户: /brainstorming 我要给网站添加用户登录功能
Claude (Brainstorming 技能触发):
  好的，在开始之前我需要澄清几个问题：
  1. 登录方式：邮箱+密码、手机号+验证码，还是第三方登录？
  2. 是否需要"记住我"功能？
  3. 登录失败时如何提示用户？
  ...
用户: 我们只需要邮箱+密码登录，简单提示错误即可。
Claude:
  明白了。需求分析结果如下：用户登录功能需支持邮箱和密码输入，密码加密存储；登录失败时前端显示错误消息；登录成功后返回用户信息。请确认是否继续下一步（/writing-plans）。
用户: 继续
Claude: /writing-plans
Claude（Writing Plans 技能触发）:
  根据需求，已为「用户登录」功能生成实施计划：
  - 任务1：在 `src/models/user.js` 创建用户表模型（字段：email, passwordHash）。**先写一个失败测试**，验证新注册用户能登录。
  - 任务2：在 `src/auth/login.js` 实现登录逻辑（验证密码并生成 JWT）。**先写一个失败测试**，确保给定正确凭证可登录。
  - 任务3：在前端 `src/components/LoginForm.vue` 添加登录表单（email/password）。**先写一个失败测试**，检查表单提交调用 Login API。
  请确认计划并开始执行。
用户: 确认
Claude:
  计划已生成，开始执行任务...（执行命令 `/execute-plan`）
Claude:
  创建隔离的 Git 工作区...（`git worktree add -b feature/login .claude/branches/feature/login`）
  开始第1个子代理任务：TDD 循环...
  先写测试 `test/user.test.js`：验证新注册用户能登录【红灯】...
  编写实现：`src/models/user.js` 创建模型，新增字段 passwordHash，登录时对比哈希【绿灯】...
  运行测试...全部通过！
  提交更改（`git add && git commit`）。
  开始第2个任务...
  写测试 `test/auth.test.js`：使用已注册用户验证登录逻辑【红灯】...
  实现 `src/auth/login.js`：查找用户并验证密码哈希，生成 JWT【绿灯】...
  测试通过！
  开始第3个任务...
  写测试 `test/loginForm.test.js`：模拟登录表单提交并检查调用 Login API【红灯】...
  实现 `src/components/LoginForm.vue`：添加表单并连接后端接口【绿灯】...
  测试通过！所有任务完成。
Claude:
  所有测试已通过。现在进行代码审查。（/request-code-review）
Claude（Request Code Review 技能触发）:
  正在审查任务...
  * 任务1模块：命名规范符合规范，无问题。
  * 任务2模块：发现一个潜在问题——密码哈希未设置盐值，建议增加。
  * 任务3模块：前端提交缺少错误捕捉，建议完善提示逻辑。
  发现1个重要问题，请修复后重审。
用户: 好的，我来修复
Claude:
  问题已修复，测试全部通过。代码审查通过。
Claude:
  准备合并分支（finish-branch）... 合并成功，功能分支关闭。

说明： 上述案例中，用户依次执行 /brainstorming、/writing-plans、确认并 /execute-plan 触发编码。AI 创建了隔离的 Git 工作区，并通过 TDD 循环完成了三个任务。产出的内容包括需求规格、任务清单、测试结果、代码片段和审查报告。/request-code-review 触发自动审查并反馈问题，修复后完成合并。所有命令（如 /execute-plan、/request-code-review）可直接在 Claude Code 环境中使用。

技能总览表

• spec-kit 官方仓库
• SDD——规格驱动开发
• spec-kit 详细流程

快速开始

安装 spec-kit

# 安装指定的稳定版本（推荐——将 vX.Y.Z 替换为最新标签）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或安装 main 分支的最新版本（可能包含未发布的变更）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 升级 spec-kit
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

初始化项目

# 创建新项目
specify init <PROJECT_NAME>

# 或在现有项目中初始化
specify init . --ai claude

# 指定 AI 编程代理并使用 skills
specify init . --ai claude --ai-skills

# 或
specify init --here --ai claude

# 检查已安装的工具
specify check

确定项目原则

在项目目录中启动 AI 助手。大多数代理会将 spec-kit 暴露为 /speckit.* 斜杠命令；Codex CLI 在技能模式下使用 $speckit-*。

使用 /speckit.constitution 命令创建项目的管理原则和开发指南，指导后续开发：

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

创建规格说明

用 /speckit.specify 命令描述你想要构建的内容。关注**「做什么」和「为什么做」**，而不是技术栈。

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

制定技术实施计划

用 /speckit.plan 命令提供技术栈和架构选择：

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

拆解任务

使用 /speckit.tasks 根据实施计划生成可执行的任务列表：

/speckit.tasks

执行任务

使用 /speckit.implement 执行所有任务，按照计划构建你的功能：

/speckit.implement

斜杠命令速查

核心命令

可选命令

spec-kit 命令参考

# 基础项目初始化
specify init my-project

# 指定 AI 助手
specify init my-project --ai claude

# 初始化并支持 Cursor
specify init my-project --ai cursor-agent

# 初始化并支持 Qoder
specify init my-project --ai qodercli

# 初始化并支持 Windsurf
specify init my-project --ai windsurf

# 初始化并支持 Kiro CLI
specify init my-project --ai kiro-cli

# 初始化并支持 Amp
specify init my-project --ai amp

# 初始化并支持 SHAI
specify init my-project --ai shai

# 初始化并支持 Mistral Vibe
specify init my-project --ai vibe

# 初始化并支持 IBM Bob
specify init my-project --ai bob

# 初始化并支持 Pi Coding Agent
specify init my-project --ai pi

# 初始化并支持 Codex CLI
specify init my-project --ai codex --ai-skills

# 初始化并支持 Antigravity
specify init my-project --ai agy --ai-skills

# 初始化并支持 Forge
specify init my-project --ai forge

# 初始化并为不支持的代理提供通用支持
specify init my-project --ai generic --ai-commands-dir .myagent/commands/

# 初始化并支持 PowerShell 脚本（Windows/跨平台）
specify init my-project --ai copilot --script ps

# 在当前目录初始化
specify init . --ai copilot
# 或使用 --here 标志
specify init --here --ai copilot

# 强制合并到当前（非空）目录，无需确认
specify init . --force --ai copilot
# 或
specify init --here --force --ai copilot

# 跳过 Git 初始化
specify init my-project --ai gemini --no-git

# 启用调试输出
specify init my-project --ai claude --debug

# 使用 GitHub Token 进行 API 请求（适用于企业环境）
specify init my-project --ai claude --github-token ghp_your_token_here

# 默认情况下，Claude Code 会在项目中安装 skills
specify init my-project --ai claude

# 在当前目录初始化并使用 agent skills
specify init --here --ai gemini --ai-skills

# 使用时间戳分支编号（适用于分布式团队）
specify init my-project --ai claude --branch-numbering timestamp

# 检查系统需求
specify check

扩展与预设

.specify/templates/overrides/         # 本地项目覆盖（优先级最高），无需创建完整预设即可一次性调整当前项目
.specify/presets/templates/           # 自定义扩展和核心模板
.specify/extensions/templates/        # 增强 spec-kit 的能力
.specify/templates/                   # spec-kit 的核心内置模板

Extensions（扩展）

当需要超越 spec-kit 核心的功能时，使用扩展。扩展会引入新的命令和模板——例如，添加内置 SDD 命令未覆盖的领域特定工作流、集成外部工具，或添加全新的开发阶段。它们扩展了 spec-kit 的能力边界。

例如，扩展可以添加 Jira 集成、实现后的代码审查、V-Model 测试追溯，或项目健康度诊断。

社区扩展

specify extension search

# 安装扩展
specify extension add <extension-name>

Presets（预设）

当需要改变 spec-kit 的工作方式但不添加新功能时，使用预设。预设会覆盖核心及已安装扩展自带的模板和命令——例如，强制使用合规导向的规格格式、采用领域特定术语，或将组织标准应用于计划和任务。它们定制了 spec-kit 及其扩展生成的制品与指令。

举例来说，预设可以重构规格模板以要求监管追溯、调整工作流以适配采用的方法论（如敏捷、看板、瀑布、Job-to-be-Done 或领域驱动设计）、在计划中增加安全审查关卡、强制测试优先的任务排序，或将整个工作流本地化为不同语言。pirate-speak 演示展示了自定义的深度。多个预设可以按优先级顺序叠加使用。

• 社区预设
• 预设说明

specify preset search

# 安装预设
specify preset add <preset-name>

open-spec

待更新……

Next.js 15 带来了诸多强大特性，让构建现代 Web 应用变得前所未有的简单。本指南将从基础概念入手，系统性地带你了解 App Router 的完整生态——从路由系统、布局管理，到数据获取、渲染策略和错误处理，帮助你建立全面的知识框架。

App Router 基础

App Router 是现代 Next.js 应用的基石。它基于文件系统路由，目录结构即对应页面路径。下面是一个简单的路由示例：

// app/page.tsx
export default function HomePage() {
  return (
    <main>
      <h1>欢迎使用 Next.js 15</h1>
    </main>
  )
}

在 app 目录下创建的文件会自动映射为对应的路由：

布局系统

布局是 Next.js App Router 的一大亮点，它让页面间的共享 UI 变得异常简单。

根布局

每个应用都必须有一个根布局（app/layout.tsx），它包裹所有页面：

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh">
      <body>
        <Header />
        <main>{children}</main>
        <Footer />
      </body>
    </html>
  )
}

嵌套布局

你可以在任意路由层级添加 layout.tsx，布局会自动嵌套。导航时布局保持状态，不会重新渲染：

// app/blog/layout.tsx
// 所有 /blog/* 页面共享此布局
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div>
      <Sidebar />
      <article>{children}</article>
    </div>
  )
}

模板

模板（template.tsx）与布局类似，但每次导航都会重新渲染，适合需要重置状态的场景（如页面试点追踪）：

// app/blog/template.tsx
export default function BlogTemplate({
  children,
}: {
  children: React.ReactNode
}) {
  return <div className="page-enter-animation">{children}</div>
}

路由进阶

路由组

使用 (groupName) 目录结构组织路由，不会影响 URL 路径。适用于将不同模块的路由分组，或为不同组使用不同布局：

app/
  (marketing)/
    page.tsx          // /
    about/page.tsx    // /about
  (shop)/
    products/
      page.tsx        // /products
    cart/page.tsx     // /cart

并行路由

通过命名插槽（@slotName）在同一布局中同时渲染多个页面，适合仪表盘或多区域页面：

// app/layout.tsx
export default function Layout({
  children,
  team,
  analytics,
}: {
  children: React.ReactNode
  team: React.ReactNode
  analytics: React.ReactNode
}) {
  return (
    <>
      {children}
      <div className="grid grid-cols-2">
        {team}
        {analytics}
      </div>
    </>
  )
}

加载与错误处理

Next.js 15 为每个路由段提供了内置的加载和错误边界。

加载界面

添加 loading.tsx 即可在页面加载时显示骨架屏或加载动画，配合流式渲染实现即时的加载反馈：

// app/blog/loading.tsx
export default function Loading() {
  return (
    <div className="space-y-4">
      <Skeleton className="h-8 w-3/4" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-2/3" />
    </div>
  )
}

错误边界

error.tsx 会包裹路由段，捕获渲染中的异常。必须是客户端组件：

// app/blog/error.tsx
'use client'

export default function ErrorPage({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>出错了</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>重试</button>
    </div>
  )
}

404 页面

通过 not-found.tsx 自定义 Not Found 界面，或调用 notFound() 函数主动触发：

// app/not-found.tsx
export default function NotFound() {
  return (
    <div>
      <h1>404 - 页面未找到</h1>
      <Link href="https://charliefei.github.io/">返回首页</Link>
    </div>
  )
}

全局错误

global-error.tsx 包裹整个应用，仅在根布局出现严重错误时使用（需包含 <html> 和 <body> 标签）：

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>应用发生严重错误</h2>
        <button onClick={() => reset()}>重试</button>
      </body>
    </html>
  )
}

核心特性

• 服务端组件：默认在服务器端渲染，减少客户端 JavaScript 体积，提升首屏加载性能。可直接访问数据库和文件系统，无需暴露 API 端点。
• 流式渲染：支持将 HTML 分块渐进式传输到客户端，用户可以更快看到页面内容，无需等待整个页面完全生成。配合 loading.tsx 实现流畅的加载体验。
• Metadata API：通过导出 metadata 对象或 generateMetadata 函数，以类型安全的方式定义页面标题、描述、Open Graph 等元数据，轻松优化 SEO。
• Server Actions：在服务端组件中直接定义表单提交和数据变更逻辑，无需手动创建 API 路由，简化前后端交互。支持渐进增强（JavaScript 不可用时退化为传统表单提交）。

数据获取

Next.js 15 提供了灵活的数据获取方式，你可以在服务端组件中直接使用 async/await：

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts')
  return res.json()
}

export default async function PostsPage() {
  const posts = await getPosts()
  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

得益于服务端组件的特性，数据获取在服务器端完成，不会暴露 API 凭据，也无需客户端加载额外数据请求逻辑。

fetch 缓存策略

内置的 fetch 支持细粒度的缓存控制：

// 静态数据请求——默认行为，缓存结果
const staticData = await fetch('https://...')

// 动态数据请求——每次请求重新获取
const dynamicData = await fetch('https://...', { cache: 'no-store' })

// 基于时间的增量再验证——每 10 秒重新获取一次
const revalidatedData = await fetch('https://...', {
  next: { revalidate: 10 },
})

数据库查询

服务端组件可以直接查询数据库，无需编写 API 路由：

export default async function UserProfile({ params }: { params: { id: string } }) {
  const user = await db.users.findUnique({
    where: { id: params.id },
  })

  return <div>{user.name}</div>
}

渲染策略

Next.js 15 提供多种渲染模式，可根据页面特性灵活选择。

静态渲染（Static Rendering）

默认渲染方式。路由在构建时渲染，结果被缓存并可被 CDN 分发。适合内容页面、博客文章等不频繁变化的内容。

export const dynamic = 'force-static'

动态渲染（Dynamic Rendering）

路由在每次请求时动态渲染。适合个性化内容、实时数据等场景：

export const dynamic = 'force-dynamic'

增量静态再生成（ISR）

结合静态与动态的优势——静态提供，按需更新。适合数据定期变化但不要求实时的场景：

// 页面级别 ISR
export const revalidate = 3600 // 每 1 小时重新生成

路由段配置

每个路由段可以通过导出的配置项精细控制行为：

export const dynamic = 'auto'           // 静态/动态自动选择
export const dynamicParams = true        // 未生成的动态参数是否自动处理
export const revalidate = false          // 重新验证间隔（秒）
export const fetchCache = 'auto'         // fetch 缓存策略
export const runtime = 'nodejs'          // 运行时环境
export const preferredRegion = 'auto'    // 部署区域

中间件

中间件（middleware.ts）在请求完成之前执行，可用于重定向、重写、鉴权、国际化路由等场景：

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 基于 Cookie 重定向用户
  if (!request.cookies.has('session')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

// 配置匹配路径
export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*'],
}

总结

Next.js 15 为构建高性能 Web 应用提供了坚实而优雅的基础。本文涵盖了从路由系统、布局管理、数据获取，到渲染策略和错误处理的核心概念。关键要点回顾：

• 文件系统路由让页面组织结构一目了然
• 布局与加载边界提供了优雅的 UI 组合与用户体验
• 服务端组件简化了数据获取并提升了性能
• 多样的渲染策略让你在不同场景下选择最优方案
• 内置错误处理确保应用的健壮性

以上只是 Next.js 能力的一部分，建议从这些基础入手，在实践中逐步探索更多高级特性。