Redwood v3 教程前置条件全解析:环境版本要求、依赖知识清单与升级路径
Redwood v3 教程前置条件全解析:环境版本要求、依赖知识清单与升级路径
本篇指南对应 Redwood v3 系列官方教程第一章的开篇《Prerequisites》,聚焦于开始 Redwood 全栈开发教程之前必须满足的软硬件前置条件:需要掌握的技术栈基础、Node.js 与 Yarn 的精确版本要求、安装失败的判定机制,以及从旧版本 Redwood 项目安全升级到可跟随教程版本的两步流程。读完本文,你将能独立完成开发环境自检、修复版本不兼容问题,并理解 Redwood 在安装引导阶段如何通过源码级的引擎检查来拦截不兼容环境。
前置知识:Redwood 站在哪些巨人的肩膀上
Redwood 本身是一个"胶水式"全栈框架,它将若干成熟的开源技术编排在一起,让全栈 Web 开发更简单。因此,官方教程在第一章就明确列出了四个假定读者已经熟悉的领域,它们也是后续教程章节反复出现的基础概念:
- React:Redwood 的 Web 端(
web侧)完全基于 React 构建,页面、组件、Cell、路由均以 React 心智模型组织; - GraphQL:Redwood 的 API 端(
api侧)以 GraphQL 作为数据交换协议,Service、SDL、Resolver 都围绕 GraphQL 展开; - Prisma:Redwood 的数据模型与数据库迁移由 Prisma 驱动,
schema.prisma是数据建模的单一事实来源; - Jamstack 部署:Redwood 的"前后端分离、静态预渲染 + 服务端函数"架构天然契合 Jamstack 的部署模型,教程末章的部署环节会用到这一概念。
不过官方教程也给出了明确的态度:"Don't panic!"——即使你对上述技术几乎一无所知,也可以顺着教程走完。你可能会在术语上偶尔迷失,但这并不致命;关键在于理解"Redwood 在原生实现之上提供了什么",而这正是 Redwood 的核心价值。作者建议:先完整走一遍教程,再独立构建自己的项目,遇到具体问题(例如 "prisma select only some fields")再按需搜索深挖,会比一次性同时学习所有底层技术更容易定位问题边界。
提示:这些前置技术分别对应 React、GraphQL、Prisma 与 Jamstack 的官方文档,教程不会替读者重讲它们的基础知识,遇到陌生术语时可随时回到对应文档查漏补缺。
Redwood 版本要求:至少 1.0.0,以及两步升级法
完成本教程需要 Redwood 至少 1.0.0 版本(对应 v3.x 系列教程的成文基线)。如果你是第一次使用 Redwood,无需担心版本问题——在创建应用骨架时,最新稳定版本会被自动安装。
对于已经用旧版本创建过站点的开发者,官方提供了一套两步升级流程,确保升级过程可控、可回退:
- 逐版本应用代码修改:对升级路径中的每一个中间版本,先阅读该版本 Release Notes 中的 "Code Modifications"(代码修改)一节,把所需的迁移改动逐一应用到你的项目;
- 升级到最新版本:完成所有中间步骤后,执行升级命令:
yarn redwood upgrade
这条命令背后的实现在仓库的 upgrade 命令源码 中可以直接看到,它远不止"改个版本号"那么简单:
- 命令通过
@redwoodjs/cli-helpers记录遥测属性,并基于listr2任务列表逐步执行升级; - 支持多种参数控制升级行为:
-d, --dry-run:仅检查是否有过时包,不真正升级;-t, --tag <tag>:指定目标版本标签,合法值包括latest、rc、next、canary、experimental,或一个合法的 semver 版本号(如rw upgrade -t 0.20.1-canary.5)。源码中的validateTag会先用SEMVER_REGEX校验 semver 格式,再检查是否属于合法发布标签,两者都不匹配时会直接抛出错误终止执行;-v, --verbose:打印详细日志;--no-dedupe:跳过依赖去重(dedupe)检查;-y, --yes:跳过交互式确认提示,使用默认值直接升级。
注意:
canary、rc、experimental属于不稳定发布,官方源码注释明确警告 "canary" 版本常包含破坏性变更,升级项目时往往还需要配合 codemods 迁移脚本。
Node.js 与 Yarn 版本:硬性门槛,不满足即报错
Redwood 在安装引导阶段会对宿主机环境做强制版本校验。v3.x 教程给出的要求是:
| 依赖 | 版本要求 |
|---|---|
| Node.js | >=14.19 且 <=16.x |
| Yarn | >=1.15 |
只要系统版本不满足任一条件,安装引导(installation bootstrap)就会直接以 ERROR 结束,而不是给出警告后继续。因此,动手安装前请先在终端确认当前环境:
node --version
yarn --version
如果输出不满足上述范围,请先升级对应工具,再继续 Redwood 的安装流程。
源码视角:引擎检查是如何强制生效的
版本校验并非文档上的"建议",而是有真实代码兜底的硬约束。在 create-redwood-app 的引导实现 中:
- 安装程序会读取模板项目
package.json中的engines字段(见 JS 模板 与 TS 模板 的"engines"配置),这是版本要求的单一权威来源; - 通过
check-node-version库对 Node 与 Yarn 的版本进行实际检测,再用semver做比较; - 检测失败时,程序会区分两种情况:
- 当前 Node 低于最低要求:直接
displayError并process.exit(1),提示使用nvm或corepack切换到兼容版本,中止安装; - 当前 Node 高于要求但超出支持范围:给出
displayWarning,说明这可能与部分部署目标(尤其是 AWS Lambda 运行时的 Node 版本)不兼容,并弹出交互提示,由用户选择 "Override error and continue install"(忽略并继续)或 "Quit install"(退出安装)。
- 当前 Node 低于最低要求:直接
也就是说,即使你在交互界面选择"忽略错误继续",也只会出现在"版本过高"的警告场景;版本过低则没有任何绕过的余地。这也解释了为什么文档会强调"务必先检查再安装"。
版本要求的演进:以当前仓库主干为参照
值得注意的是,Redwood 的版本要求随主版本迭代不断收紧。以本仓库主干(对应更高版本 Redwood)为例,engines 字段已变为 "node": "=20.x",Yarn 则通过根 package.json 的 packageManager 字段(yarn@4.6.0)由 Corepack 锁定到现代 Yarn 版本——这与 v3.x 教程要求的 >=14.19 <=16.x 已完全不同。如果你参考的是本仓库主干文档(对应更高版本教程),请以当时的文档要求为准;本文论述的 >=14.19 <=16.x / yarn >=1.15 仅适用于 v3.x 系列教程场景。
安装 Node.js 与 Yarn 的推荐路径
v3.x 教程在版本检查小节附带了针对"首次安装"的工具选型建议:
1. Yarn
推荐直接按照 Yarn 官方(Yarnpkg.com)的安装说明进行安装,保证版本号满足 >=1.15。
2. Node.js
- 首选 LTS 版本:建议安装 Nodejs.org 推荐的 LTS(长期支持)版本,而不是最新的 Current 版本——教程明确说明 Current 版本不受支持;
- nvm 管理多版本:
nvm是同一系统上管理多个 Node 版本的利器,但需要额外的安装与学习成本。可按 nvm 官方安装说明操作;Mac 用户若装有 Homebrew,也可以直接brew install nvm;Windows 用户请使用 nvm-windows 发行版。
仓库中还收录了一篇完整的 using-nvm 实操指南,详细覆盖了 nvm 的安装、版本切换与在 Redwood 项目中的应用,建议 Windows 与多版本需求的开发者配合阅读。
Windows 开发者:额外的环境配置要求
JavaScript 开发在 Windows 上除了 Yarn 与 npm 之外还有额外的系统级要求(例如原生模块编译工具链等)。v3.x 教程为 Windows 用户单独准备了环境搭建指南,请务必在开始 Redwood 教程前完成该设置:
结语:把前置条件当作教程的"第一道关卡"
本页虽然只是教程的序章,却承担着整个学习旅程的"准入控制"职责:前置技术栈决定了你能跟上多快,环境版本校验决定了你能不能启动。用两行命令完成自检、按两步流程完成旧项目升级、按平台指引装好 Node/Yarn 与 Windows 工具链,你就可以放心进入下一节,通过 yarn create redwood-app 创建应用骨架并启动开发服务器了(见 Installation & Starting Development)。记住:版本要求永远以你手中那个版本的官方文档为准,而本仓库的模板 engines 字段与 CLI 源码,就是这些要求最可信的"源代码级证据"。