RedwoodJS 项目中的.redwood目录设计意图、文件结构与底层实现解析【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood引言在你日常使用 RedwoodJS 进行开发时项目根目录下会悄然出现一个名为.redwood的目录。它几乎不引人注意也不会出现在你的 Git 提交记录中但 RedwoodJS 的 CLI、开发服务器、类型系统、遥测和更新检查机制都依赖它来存储临时数据。本文将以__fixtures__/test-project-rsc-kitchen-sink/.redwood/README.md这份官方说明文档为骨架结合本仓库中的源码实现深入解析.redwood目录的设计意图、文件结构以及每个条目背后的实际工作机制。读完本文你将彻底理解这个目录为什么存在、其中每个文件的用途以及为什么你不需要也不应该手动管理它。重要声明.redwood目录的内容是生成物不是源码。它是 RedwoodJS 框架运行时的临时数据存储区位于每个 Redwood 项目的根目录下。以下所有关于文件用途和机制的描述均以本仓库中的源码和官方文档为依据。一、.redwood目录是什么根据.redwood/README.md的官方说明Redwood uses this.redwooddirectory to store transitory data that aids in the smooth and convenient operation of your Redwood project.transitory data临时数据是理解这个目录的关键。RedwoodJS 是一个全栈框架其 CLIyarn rw、开发服务器、GraphQL schema 生成、TypeScript 类型生成、遥测统计、后台任务等都需要在多次进程运行之间共享一些状态。这些状态不适合放在源码目录中会被提交到 Git也不适合放在全局缓存中无法与具体项目绑定因此 RedwoodJS 将它们集中放在项目根目录下的.redwood目录中。从源码层面看.redwood目录的路径由 packages/project-config/src/paths.ts 中的getPaths()统一管理它是框架内部所有模块获取.redwood路径的唯一入口generated: { base: path.join(BASE_DIR, .redwood), schema: path.join(BASE_DIR, .redwood/schema.graphql), types: { includes: path.join(BASE_DIR, .redwood/types/includes), mirror: path.join(BASE_DIR, .redwood/types/mirror), }, prebuild: path.join(BASE_DIR, .redwood/prebuild), },其中BASE_DIR是项目的根目录即包含redwood.toml的目录。无论是 CLI 插件、遥测导出器、更新检查器还是类型生成器都通过getPaths().generated.base来定位这个目录而不是硬编码路径。这种集中管理的方式保证了框架各模块之间的一致性。二、你需要在日常开发中处理它吗完全不需要。根据官方文档No. You shouldnt have to create, edit or delete anything in this directory in your day-to-day work with Redwood..redwood目录是自动生成、自动维护的。创建新项目时create-redwood-app生成的模板会在 packages/create-redwood-app/templates/js/gitignore.template 中写入.redwood/*因此它默认被 Git 忽略不会进入版本控制系统。这意味着不要手动创建目录或其中的文件——CLI 会在需要时自动创建不要编辑其中的内容——任何手动修改都可能被框架下次运行覆盖不要删除它——如果删除了框架会在下次运行时重新生成可能会经历一次类型生成、schema 生成的重新初始化。官方文档还特别提醒这个 README 可能不会一直完整记录目录中的全部内容因为随着框架演进.redwood中可能出现尚未被文档化的新文件或子目录这通常不是问题。三、.redwood目录中的文件根据官方文档.redwood目录根级别包含四个文件。下面逐一解析其用途并结合仓库源码说明其生成机制。3.1commandCache.jsonCLI 插件命令缓存官方描述包含映射关系用于辅助 Redwood CLI 高效执行命令。源码实现这个文件由 packages/cli/src/lib/plugin.js 中的loadCommandCache()和saveCommandCache()管理。commandCache.json的核心作用是缓存yargs 命令信息特别是那些懒安装lazy install依赖的插件命令。Redwood CLI 支持通过redwood.toml中的[experimental.cli.plugins]配置加载第三方插件如redwoodjs/cli-storybook-vite、redwoodjs/cli-data-migrate这些插件可能尚未安装但 CLI 在--help输出中仍需要展示它们的命令名称、别名和描述。因此loadCommandCache()先读取commandCache.json中缓存的命令信息并将其与代码中定义的PLUGIN_CACHE_DEFAULT默认缓存合并默认缓存优先确保缓存与当前框架版本保持一致同时注入_builtin字段列出 CLI 内置的命令列表build、check、diagnostics、console、dev、generate、serve、test等每次执行涉及插件的命令后saveCommandCache()将最新的命令映射写回commandCache.json。从源码中可以看到这个缓存文件还带有一个简单的格式校验逻辑——如果读取到的缓存格式与预期不符例如值不是对象而是数组则丢弃本地缓存回退到默认缓存。这保证了缓存文件损坏或格式过时时CLI 仍能正常工作。3.2schema.graphql自动生成的 GraphQL Schema官方描述由 Redwood 项目自动生成的 GraphQL schema。源码实现这个文件是 RedwoodJS 的核心生成物之一路径定义在 packages/project-config/src/paths.ts 中path.join(BASE_DIR, .redwood/schema.graphql)。当你执行yarn rw dev或yarn rw build时Redwood 会扫描你的api/src目录services、directives、graphql 等结合api/db/schema.prisma中的数据库模型生成完整的 GraphQL schema并写入.redwood/schema.graphql。这个 schema 随后被 GraphQL 服务器redwoodjs/graphql-server加载用于启动 GraphQL 端点。同时它也作为类型生成器的输入为 web 端生成对应的 TypeScript 类型。3.3telemetry.txt遥测匿名 ID官方描述包含一个用于遥测的唯一 ID每 24 小时轮换一次以保护项目的匿名性。源码实现这个文件由 packages/cli/src/telemetry/resource.js 管理。逻辑如下const telemetryFile path.join(getPaths().generated.base, telemetry.txt) if (!fs.existsSync(telemetryFile)) { fs.ensureFileSync(telemetryFile) } if (fs.statSync(telemetryFile).mtimeMs Date.now() - 86400000) { // 86400000 is 24 hours in milliseconds, we rotate the UID every 24 hours fs.writeFileSync(telemetryFile, UID) } else { // 读取已存储的 UID并校验是否为合法 UUID }具体机制是首次运行时生成一个新的 UUID v4 并写入telemetry.txt如果文件修改时间距今超过 24 小时则生成新的 UUID 并覆盖如果文件较新且内容是一个合法的 UUID则复用该值读取失败时静默忽略使用内存中新生成的 UUID。这个 ID 不包含任何项目信息仅用于在遥测后端将同一次 CLI 会话的多次 span 关联起来。由于每 24 小时轮换它无法被用于长期追踪某个项目。3.4test.db测试用 SQLite 数据库官方描述运行测试时使用的 SQLite 数据库。源码实现Redwood 的测试工具链基于 Jest/Vitest在执行 API 测试时会使用 SQLite 数据库来隔离测试数据避免污染开发或生产数据库。这个文件在运行测试时自动创建于.redwood/test.db。相关路径管理同样通过getPaths()体系完成。四、.redwood目录中的子目录4.1locks/跨进程任务锁官方描述存储 Redwood 用于跨进程跟踪异步/后台任务执行的临时文件。源码实现这个目录由 packages/cli/src/lib/locking.js 管理。它以文件系统作为跨进程互斥锁setLock(identifier)在locks/目录下创建以 identifier 命名的空文件isLockSet(identifier)检查文件是否存在并检查文件创建时间——锁的有效期为 1 小时3600000 毫秒超过则视为过期锁并自动清除unsetLock(identifier)删除锁文件clearLocks()支持清除指定锁或全部锁。这个机制被更新检查UPDATE_CHECK、UPDATE_CHECK_SHOW等后台任务使用防止多个进程同时执行同一后台任务。例如在 packages/cli/src/lib/updateCheck.js 中shouldCheck()和shouldShow()都会先检查对应锁是否已设置避免重复检查或重复弹窗。4.2logs/后台任务日志官方描述存储后台任务如更新检查的日志文件。源码实现由 packages/cli/src/lib/background.js 中的spawnBackgroundProcess()管理。Redwood CLI 会以分离进程detached process方式运行后台任务如遥测上报、更新检查并将这些进程的 stdout/stderr 重定向到.redwood/logs/目录下的日志文件日志文件按任务名命名例如updatecheck.out.log、updatecheck.err.log、telemetry.out.log等文件名中的非字母数字字符会被替换为下划线并转小写每个日志文件开头会写入包含时间、任务名、命令和参数的头部信息方便排查问题。4.3prebuild/构建产物中的转译后 JavaScript官方描述存储 Redwood 构建过程中生成的转译后 JavaScript。源码实现路径定义在 packages/project-config/src/paths.ts。Redwood 在构建过程中会将部分源码例如 api 侧的某些模块通过 Babel 转译为 JavaScript存放在prebuild/目录中供构建管线使用。这个目录与最终部署产物api/dist、web/dist不同它是构建过程中的中间产物。4.4telemetry/待上报的遥测数据官方描述存储 Redwood CLI 近期生成的遥测数据。你可以检查这些文件了解 Redwood 匿名收集了哪些信息。源码实现这是 Redwood 遥测系统中最透明的部分。遥测采集使用 OpenTelemetry 规范packages/cli/src/telemetry/exporter.js 定义了一个CustomFileExporter将采集到的 spans 以 JSON 格式先写入本地文件而不是直接发送到网络每个 span 文件以Date.now()时间戳命名例如1699999999999.json文件内容是一个 JSON 数组包含本次 CLI 会话的所有遥测 span采集的 span 包括执行的命令、环境信息Node/Yarn 版本、操作系统、Shell、CPU 核数、内存、项目复杂度指标路由数、预渲染路由数、service 数、cell 数、页面数、启用的实验特性、CI 环境标识等见 resource.js。随后packages/cli/src/telemetry/send.js 在后台进程中读取这些文件通过 OTLP HTTP 导出器发送到遥测收集端发送成功后文件被重命名为_前缀如_1699999999999.json表示已发送每个已发送文件的 span 会被重写并保留最近 8 个文件用于透明审查超过 8 个的旧文件会被自动删除。这就意味着你随时可以打开.redwood/telemetry/目录查看 Redwood 实际收集了哪些数据完全符合官方文档中transparency透明性的承诺。4.5types/类型生成结果官方描述存储类型生成的结果。源码实现路径定义在 packages/project-config/src/paths.ts包含两个子目录types/includes/存放自动生成的全局类型声明如all-*、api-*、web-*系列声明文件types/mirror/存放镜像类型即对每个源码文件的模块声明镜像让 TypeScript 能识别 Redwood 特有的导入路径。这些类型被项目的tsconfig.json/jsconfig.json引用。以 packages/create-redwood-app/templates/js/api/jsconfig.json 为例新项目模板会将这些生成类型目录加入paths映射和include列表。因此当你在编辑器中编写import { ... } from src/services/...或使用 Redwood 自动生成的类型时编辑器提示和类型检查依赖的就是.redwood/types/目录中的内容。如果删除.redwood目录IDE 的类型提示会暂时失效直到重新运行yarn rw dev或yarn rw build触发类型重新生成。4.6updateCheck/更新检查结果官方描述存储 Redwood 更新检查的结果。源码实现由 packages/cli/src/lib/updateCheck.js 管理。该模块实现了完整的检查更新并提示机制后台进程通过spawnBackgroundProcess以yarn node updateCheckExecute.js方式运行读取项目package.json中的redwoodjs/core版本作为本地版本根据redwood.toml中notifications.versionUpdates配置的 npm tag默认如latest查询远端最新版本将结果本地版本、各 tag 的远端版本、checkedAt检查时间、shownAt展示时间持久化到.redwood/updateCheck/data.json检查周期和提示周期都是 24 小时CHECK_PERIOD和SHOW_PERIOD见 updateCheck.js只有当远端存在更新的版本且距离上次提示超过 24 小时时才会在 CLI 中展示升级提示框。这个机制与locks/目录配合使用检查任务和提示展示各自持有独立的锁UPDATE_CHECK和UPDATE_CHECK_SHOW避免多个终端会话重复触发。4.7studio/rw studio数据官方描述用于存储rw studio命令的数据。源码实现rw studio是 Redwood 提供的开发期调试工具提供数据库浏览、GraphQL 探索、任务监控等功能它需要在.redwood/studio/目录中存储自己的运行时数据例如本地数据库副本、会话数据等。与test.db类似这部分数据也是本地生成物不应提交到版本控制。五、扩展知识.redwood中的其他使用场景除了官方文档列出的条目外从源码中还可以发现.redwood目录的一些其他用途这些在文档中有预告——你可能发现尚未被文档化的其他文件console_historypackages/cli/src/commands/consoleHandler.js 将rw consoleRedwood REPL 控制台的命令历史保存在.redwood/console_history方便跨会话复用历史命令。测试配置rw test的处理器会将测试相关的临时配置或状态写入.redwood目录见 packages/cli/src/commands/testHandler.js。升级逻辑rw upgrade命令在升级前后也会借助.redwood目录暂存状态见 packages/cli/src/commands/upgrade.js。这些都属于transitory data的范畴进一步印证了.redwood目录作为框架内部临时状态集散地的定位。六、遥测与隐私你完全可以掌控官方文档明确说明RedwoodJS 收集的是完全匿名的遥测数据且这些数据就保存在.redwood/telemetry/目录中你可以随时查看。从源码还可以确认几种关闭遥测的方式见 packages/cli/src/telemetry/send.js 的提示输出环境变量设置REDWOOD_DISABLE_TELEMETRY环境变量CLI 参数在执行yarn rw命令时传入--no-telemetry标志检查源码直接阅读.redwood/telemetry/下的 JSON 文件确认收集内容的范围。这种本地落盘 可审计 可关闭的设计是 Redwood 对遥测透明性承诺的具体体现。七、总结.redwood目录是 RedwoodJS 全栈框架运行时的临时数据中枢它承载了四类核心职责职责对应条目关键源码位置CLI 辅助commandCache.json、console_historypackages/cli/src/lib/plugin.js代码生成schema.graphql、types/、prebuild/packages/project-config/src/paths.ts后台任务locks/、logs/、updateCheck/packages/cli/src/lib/locking.js、packages/cli/src/lib/background.js遥测与数据telemetry.txt、telemetry/、test.db、studio/packages/cli/src/telemetry/核心结论.redwood是自动生成、自动维护的临时数据目录不需要也不应该手动干预它默认被 Git 忽略模板中的gitignore.template已配置.redwood/*不会污染版本库若误删该目录Redwood 会在下次运行yarn rw dev/yarn rw build等命令时重新生成代价只是需要重新触发一次 schema 和类型生成遥测数据完全透明、可审查、可关闭——REDWOOD_DISABLE_TELEMETRY环境变量或--no-telemetry参数即可禁用。理解了.redwood目录你就理解了 RedwoodJS 的 CLI 生态如何组织跨进程状态、如何管理代码生成产物、如何保障遥测透明性——这既是日常排障比如类型提示失效、更新检查不触发的关键线索也是深入阅读 Redwood 框架源码的绝佳切入点。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考