企业官网建设流程全解析

• 后端
• 前端
• Web框架
• 开发工具

RedwoodJS 的官方教程（Tutorial）以"从零构建一个博客引擎"为主线，带领读者完整走完一个数据库驱动的单页应用从脚手架、页面、路由、Cell、表单、认证到测试与部署的全过程。这篇导读为你说明本教程的设计初衷、为何选择博客作为教学载体、章节结构如何编排、正文中各种 Callout 提示的含义，以及开始动手前需要满足的版本与运行环境前提。读完本文，你将清楚如何规划自己的学习路径，并在 RedwoodJS 教程 的指引下逐章上手。

本教程要构建什么：一个博客引擎

教程开篇（foreword.md）就明确了目标：构建一个博客引擎（blog engine）。RedwoodJS 把多项目前成熟的技术首次整合到一起，官方称之为"数据库驱动的单页应用（database-backed single page application）的未来"——React 负责前端，GraphQL 负责 API 层，Prisma 负责数据库访问。如果你还没有接触过 Redwood，建议先阅读仓库根目录的 README.md，了解框架要解决的问题与整体定位：一个"有主见（opinionated）的全栈框架"，将 React、Vite、Prisma、Jest、Storybook、Pino 等胶合为一个整体，并可在 Serverless（Netlify、Vercel）与传统服务器（AWS、Render）之间近乎零改动地切换部署。

为什么偏偏选择博客：不算理想却是最合适的教学载体

文档中有一个值得留意的坦白：博客其实并不是 Redwood 应用最理想的形态。博客文章完全可以存进 CMS、静态生成为 HTML，再作为纯静态文件从 CDN 分发——这正是经典 Jamstack 的典型用例。既然如此，教程为什么还要选它？

原因有两点，都写在 foreword.md 中：

1. 绝大多数开发者对博客都非常熟悉，理解成本低；
2. 博客虽简单，却能覆盖教程想要演示的全部核心特性——从页面与布局、路由参数、Cell 数据获取，到表单、认证、Storybook、Jest 测试、RBAC 权限。

也就是说，博客是"以最小的心智负担覆盖最全特性面"的教学选择。从 教程目录 的章节编排可以直观看到这条覆盖面：

• 第 1 章：前置条件（prerequisites.md）、安装（installation.md）、文件结构（file-structure.md）、首页（first-page.md）、布局（layouts.md）、第二个页面（second-page.md）；
• 第 2 章：动态数据（getting-dynamic.md）、路由参数（routing-params.md）、Cell（cells.md）、支线任务（side-quest.md）；
• 第 3 章：表单（forms.md）与数据保存（saving-data.md）；
• 第 4 章：认证（authentication.md）与部署（deployment.md）；
• 第 5 章：Storybook 与 Jest 测试（storybook.md、first-story.md、testing.md、first-test.md）；
• 第 6 章：评论区功能（comments-schema.md、comment-form.md、multiple-comments.md、the-redwood-way.md）；
• 第 7 章：基于角色的访问控制（rbac.md）。

教程的演进：从"上下两部"到"按主题分章"

如果你之前跟过更早版本的教程，可能会记得它曾分为 Part 1 与 Part 2 两部分。文档解释了这段历史：Part 2 中演示的大多数特性（如 Cell、认证、Storybook 等）在 Part 1 编写时还不存在于框架中，所以当时只能把新特性单独放进 Part 2。如今这些特性已经全部整合进框架并稳定运行，教程便按逻辑主题重新划分为章节（Chapter），也就是你现在看到的第 1～7 章的结构。这一演进信息本身也提醒学习者：RedwoodJS 的迭代速度很快，教程结构会随框架能力同步演化。

贯穿全文的 Callout：tip、caution、danger、info

正文中会反复出现几种醒目的提示块（Callout），用于补充细节、给出延伸阅读或强调重要事项。它们在 foreword.md 中被逐一演示，语法如下（Docusaurus 风格的 admonition 语法）：

:::tip 它们可能长这样…… ::: :::caution 或者有时长这样…… ::: :::danger 甚至可能长这样！ ::: :::info 这是本教程要求使用 RedwoodJS 1.0.0 及以上版本。 :::

各类 Callout 的定位：

• tip：通常对某个具体点做更深一层的说明；
• caution：提醒你可能踩坑或需要注意的地方；
• danger：强调必须重视的关键事项；
• info：给出必要的背景信息或前提条件。

一个值得注意的仓库细节：在本仓库当前主版本的 docs/docs/tutorial/foreword.md 中，caution已被更名为warning（对应 Docusaurus 的标准 admonition 类型），其余三种保持一致。如果你同时阅读多个版本的文档，看到caution与warning并存属于正常现象，语义相同。

开始之前：版本前提

教程在 Callout 中明确声明：本教程假设你使用的 RedwoodJS 版本为 1.0.0 及以上。对于首次使用 Redwood 的用户，创建应用骨架时最新版本会自动安装，无需额外处理；对于已有旧版本项目的用户，则需要先按各版本 Release Notes 中的 "Code Modifications" 逐版本执行代码改造，再运行yarn redwood upgrade升级到最新版本。

运行环境要求

安装过程中 RedwoodJS 会校验 Node 与 Yarn 的版本（详见 prerequisites.md）：

若系统版本不满足任一要求，安装引导会直接报错。动手前可在终端确认：

node --version yarn --version

版本说明：以上版本区间是 v2.x 教程文档所对应的历史要求。如果你使用的是仓库中更新的版本（例如主文档 docs/docs/tutorial/foreword.md 已要求 7.0.0 及以上），请以对应版本文档中的要求为准，并优先使用 Node 官方 LTS 版本。

建议的前置知识

教程假设读者对以下技术已有基本概念（不熟悉也不必恐慌，可以边做边查）：

• React
• GraphQL
• Prisma
• Jamstack 部署模型

正如 prerequisites.md 所说，教程不会停下来逐一讲解这些技术的全部细节；遇到不懂的术语先跳过即可，随着学习深入，你会逐渐看清"哪些能力是 Redwood 在原生技术栈之上提供的"。

教程全景与进阶路径

教程的整体节奏并非一次性拉满：第 4 章之后有一篇 intermission.md 中场休息，之后从第 5 章起转入 Storybook、Jest 与评论功能，并假设你已具备完整的测试套件与若干 Storybook 组件。如果你从中场之后继续，官方建议克隆redwood-tutorial示例仓库（包含前四章的成果、Tailwind 样式、起始测试套件与若干 Storybook 组件），执行：

git clone <redwood-tutorial 示例仓库地址> cd redwood-tutorial yarn install yarn rw prisma migrate dev yarn rw prisma db seed yarn rw g secret

将yarn rw g secret输出的随机字符串写入项目根目录.env文件的SESSION_SECRET变量，然后运行yarn rw dev启动开发服务器即可。该密钥用于 第 4 章认证 中 dbAuth 安全 Cookie 的加密。若你选择在自有代码库上继续，记得确保本地数据库与生产环境一致（例如部署到 Netlify 时 schema 中切换为 PostgreSQL，本地也需相应切换，参见 local-postgres-setup.md）。

走完全程之后，afterword.md 提供了下一步方向：调用第三方 API（using-a-third-party-api.md）、构建无 API 应用（disable-api-database.md）等实战指南。现在，从 第 1 章前置条件 开始你的 RedwoodJS 之旅吧。

• 后端
• 前端
• Web框架
• 开发工具