Remix CLI 完全指南从remix new脚手架到数据库迁移、静态资源审计与测试编排【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix导读本文以packages/cli/CHANGELOG.md为骨架系统梳理 Remix CLIremix-run/cli从 v0.1.0 到 v0.6.0 的核心能力演进remix new项目脚手架、remix doctor项目体检、remix routes路由树检视、remix db数据库命令族migrate / rollback / wipe / seed / reset / status、remix assets静态资源审计、remix test测试编排、remix.json统一配置与remix completion补全以及runRemix()可编程 CLI API。结合packages/cli/src下的源码实现与demos/bookstore真实示例你将掌握这些命令的完整参数、底层执行链路与配置优先级规则可直接落地到日常开发流程。1. CLI 包定位与运行前提remix-run/cli是 Remix 的命令行界面包v0.1.0 首次发布即提供公共的runRemix()API 以及项目脚手架、健康检查与修复、路由检视、测试运行四大类命令。用户日常敲的remix可执行文件由remix包提供remix-run/cli则暴露程序化 API源码入口。运行前提见 packages/cli/package.jsonNode.js 版本 24.3.0模块系统type: module使用 ESM依赖remix-run/assets、remix-run/data-table*sqlite / postgres / mysql、remix-run/terminal、remix-run/test以及jsonc-parser与semver。runRemix(argv, options)是唯一入口解析argv、调度到对应子命令、返回进程退出码。options支持cwd默认process.cwd()与remixVersion覆盖。典型用法import { runRemix } from remix-run/cli let exitCode await runRemix(process.argv.slice(2)) process.exit(exitCode)入口实现位于 packages/cli/src/lib/cli.ts先剥离开头的--分隔符再抽取全局选项--no-color、--config path/--configpath随后按子命令名调度到new、completion、assets、doctor、db、routes、test、version、help。命令实现全部懒加载await import(...)v0.2.0 的 patch 说明这一设计可避免无关命令在启动时加载可选依赖。全局选项说明选项含义--config path指定remix.json配置文件路径替换自动发现--no-color禁用终端颜色输出--分隔符其后参数不再解析为全局选项2.remix.json统一配置文件v0.4.0 引入v0.4.0 引入可选的静态remix.json配置文件覆盖数据库适配器、迁移与种子、remix test全部设置、remix doctor的 strict 模式。解析器对 JSONC 语法宽容支持注释与尾随逗号自动剥离 BOM见 remix-config.ts并使用jsonc-parser做树解析与精确的行/列错误定位。2.1 配置加载与优先级自动发现loadConfig(from)从给定目录默认process.cwd()向上查找最近的remix.json传入文件路径时直接读取该文件remix-config.ts。数据库命令从项目子目录执行也能找到最近的配置。优先级显式 flag 与位置参数 配置文件值 默认值。负向 flag--no-strict、--no-watch、--no-coverage、--no-quiet、--no-browser.open、--no-browser.echo可覆盖配置中的true。变更注意--config原先的测试专用含义与remix-test.config.ts/.js自动发现已被移除相关配置迁移至remix.json#test。2.2 配置结构RemixConfig顶层键为assets、db、doctor、test另有$schema指向编辑器校验用 JSON Schema。源码 remix-config.ts 与 Schema packages/cli/schema/remix.json 双源一致未知属性会直接报错Unknown property属于严格校验。assets段键类型说明allowFiles必填string[]允许被浏览器访问的文件路径与 globbasePath必填string静态资源公开 URL 前缀rootDirstring资源文件根目录相对本配置文件解析默认.allowPackagesstring[]允许通过包名暴露文件及其依赖的包denyFilesstring[]禁止被访问的文件路径与 globmountsRecordstring,string以 basePath 相对 URL 为键、目录为值的挂载表files.extensionsstring[]无需脚本/样式编译即可直接服务的附加文件扩展名db段adapter为必填三选一{ db: { adapter: { type: sqlite, filename: ./db/app.sqlite, // 或 { env: DB_PATH, default: ./db/app.sqlite } foreignKeys: true, // 可选 busyTimeout: 5000 // 可选非负整数毫秒 }, migrations: { directory: ./db/migrations, // 必填 journalTable: _remix_migrations // 可选迁移日志表名 }, seed: ./db/seed.sql // 可选 } }其他适配器remix-config.tsPostgreSQLtype: postgresconnectionString字符串或{env, default}可选maintenanceDatabase维护库用于建库/删库、template建库模板。MySQLtype: mysqluri字符串或{env, default}可选characterSet、collation。dbString支持环境变量间接引用{ env: DATABASE_URL, default: ... }。解析时已设置但为空的 env 视作未设置会回退到 defaultdatabase-command.ts。sqlite 的filename允许:memory:内存库配置中的相对路径以配置文件目录为基准解析而--connection-env覆盖时相对路径以命令调用目录为基准db.ts避免静默重定向。doctor段{ strict: true }存在 warning 级 findings 时remix doctor以退出码 1 结束。test段键类型说明files/browserFiles/e2eFilesstring[]各类型测试文件 globexcludestring[]排除 globonlystring[]按完整测试名聚焦的正则支持/re/flags字面量非法正则报错concurrencyinteger ≥ 1并发 worker 上限poolforks|threadsserver/e2e 测试 worker 池reporterspec|files|tap|dot输出格式quietboolean是否省略 skipped 测试输出setupstring导出globalSetup/globalTeardown的模块type[server,browser,e2e]运行的测试类型watchboolean文件变更自动重跑coverageobjectenabled、include/excludeglob、dir输出目录、branches/functions/lines/statements最低覆盖率百分比playwrightobjectconfigFile、projectsPlaywright 项目名、open结束后保留浏览器、echo回显浏览器 console 到 stdout所有 glob 均相对配置文件目录解析再转换为相对cwd的 POSIX 路径setup、dir、configFile等路径键也按配置目录解析remix-config.ts。3.remix new项目脚手架remix new target-dir [--app-name name] [--force]在目标目录创建新 Remix 项目new.ts。--app-name覆盖显示名--force允许写入非空目录。执行过程分三阶段并带进度输出Prepare target directory→Generate scaffold files→Finalize package.json。CHANGELOG 记录了模板的持续演进v0.2.0默认服务器改为remix/node-serve移除remix skills命令BREAKING。v0.3.0默认模板只含单个 home 路由共享 HTML 渲染迁移到中间件app/middleware/render.tsx通过请求上下文context.render读取模板新增静态资源服务public/、Remix favicon 与共享文档壳。v0.3.2/0.3.4剥离 Remix 仓库特定逻辑生产环境以NODE_ENVproduction启动、压缩浏览器资源、使用 dev server watcher而非 asset server watcher、客户端与服务端都能解析 frames脚手架包含模板.gitignoreremix doctor --fix不得通过符号链接在项目根之外创建/更新文件见 #11532。v0.4.0新项目自带npm run hmr与hmr.ts运行器。v0.5.0默认模板为客户端入口提供 preloads。仓库根目录的 template 目录即对应脚手架产物结构app/actions/、app/assets.ts、app/router.ts、app/routes.ts、hmr.ts、server.ts等。模板随包发布通过 scripts/sync-cli-template.ts 在prepack时同步。4.remix db数据库命令族v0.4.0 新增remix db系列命令v0.6.0 补齐回滚能力。命令矩阵如下帮助文本见 db.ts子命令作用特殊 flagremix db wipe --force清空当前数据库整库销毁--force必填remix db migrate [--to m]应用迁移--to仅向前推进到指定迁移--toremix db rollback [--step N \| --to m] [--dry-run]从新到旧回滚默认回滚 1 步--step/--to互斥、--dry-runremix db status展示迁移状态—remix db seed执行 SQL 种子文件--seed pathremix db reset --force清库 迁移 种子--force必填公共选项--migrations path迁移目录、--journal-table name日志表、--connection-env name从环境变量读取连接、--seed path。回滚语义v0.6.0 新增Database.migrate()早已接受direction、to、step、dryRun但 CLI 从未传递——因此此前迁移的down.sql在remix db下不可达--to只能限制向前进度。rollback修复了这条链路--step count默认 1从最新开始回滚 N 个迁移--to migration含该迁移在内回滚至它--dry-run只报告将回滚的内容不实际执行--step与--to互斥--step必须是正整数db.ts。4.1 执行链路解析parseDbCommandArgs按子命令分别解析db.tswipe/reset缺--force直接抛dbForceRequired。配置解析无--config时向上查找remix.json找不到抛remixConfigNotFoundconfig.db缺失抛dbConfigRequireddb.ts。计划合成resolveDatabaseCommandPlan将 flag 覆盖合入配置并校验 migrate/rollback/status/reset 需要迁移目录、seed 需要种子文件db.ts。适配器实例化按adapter.type懒加载remix-run/data-table-sqlite/postgres/mysql之一db.ts。sqlite 会自动创建父目录并支持:memory:postgres 支持maintenanceDatabase与templatemysql 强制multipleStatements: true以支持种子多语句。执行通过remix-run/data-table/cli的runRemixDb完成迁移与种子分别经loadMigrations、loadSeed加载db.ts。数据库连接在命令结束后统一close()若命令与关闭双双失败则抛出AggregateError。4.2 真实示例bookstoredemos/bookstore/remix.json 展示最小可用配置sqlite 迁移目录 种子{ $schema: node_modules/remix/schema/remix.json, db: { adapter: { type: sqlite, filename: ./db/bookstore.sqlite, foreignKeys: true }, migrations: { directory: ./db/migrations }, seed: ./db/seed.sql }, test: { playwright: { configFile: ./playwright.config.ts } } }迁移以时间戳_名称/up.sqldown.sql目录形式组织例如 demos/bookstore/db/migrations/20260228090000_create_bookstore_schema/up.sql 创建books、users、orders、order_items等表同名目录下的 down.sql 按依赖逆序drop table先删外键引用方password_reset_tokens、order_items、orders再删users、books。种子文件 demos/bookstore/db/seed.sql 使用幂等insert or ignore into语句可安全重复执行。典型工作流remix db migrate # 应用全部迁移 remix db status # 查看迁移状态 remix db seed # 写入种子数据 remix db rollback --step 1 # 回滚最近一个迁移 remix db rollback --to 20260228090000_create_bookstore_schema --dry-run remix db reset --force # 清库 迁移 种子5.remix doctor项目健康检查与自动修复remix doctor [--json] [--strict] [--no-strict] [--fix]检查项目环境与 Remix 应用约定doctor.ts--json以 JSON 输出 findings--strict存在 warning 级 findings 时退出码为 1--no-strict反向覆盖--fix应用低风险自动修复。strict 取值逻辑先取remix.json#doctor.strict默认false再按 argv 中出现的--strict/--no-strict顺序覆盖doctor.ts。实现细节v0.4.0 patchaction 检查被限定在app/routes.ts所需的目录与控制器路径app/actions下无关文件/目录被忽略--fix不再生成 action 控制器源码见 packages/cli/src/lib/doctor/ 下的controllers.ts、controller-findings.ts、fixes.ts。v0.3.4 起--fix在路径穿越符号链接时会阻止在项目根之外创建/更新文件见 #11532。6.remix routes路由树检视remix routes [--json | --table] [--no-headers] [--verbose]输出当前应用的路由树routes.ts--json输出规范化路由树 JSON--table扁平表格列Route / Method / Path / Owner--no-headers配合--table省略表头--verbose树/表中显示完整 owner 路径否则省略app/actions/前缀。flag 互斥校验--json不能与--table、--verbose组合--no-headers必须搭配--table。路由树由 route-map.ts 的loadRouteMap在 worker 中加载owner 缺失[missing]的节点以红色渲染便于一眼发现路由指向不存在的控制器。v0.3.0 起路由归属统一为app/actions目录结构见下节。7.remix assets静态资源审计v0.6.0 新增remix assets列出所有浏览器可达资源输出稳定的URL → 文件映射remix assets inspect url-or-file针对单个 URL 或文件路径解释其映射关系、文件类型、访问规则与状态assets.tsremix assets remix assets inspect /assets/app/actions/public/entry.ts remix assets inspect app/actions/public/entry.ts实现上命令加载remix.json#assets配置缺失抛assetsConfigRequired用createAssetServer({ ...config.assets, watch: false })以非监听模式实例化资源服务器来自remix-run/assets再分别调用getAssets()列表与getAssetDetails(input)详情最后close()释放资源。inspect输出包含Status、URL、File被拒绝时附带Denied by访问规则来源如denyFiles。配套变更新增共享的assets配置段并导出loadConfig脚手架把浏览器可达源码放在app/内各 colocatedpublic/目录浏览器运行时入口为app/actions/public/entry.ts共享的app/routes.ts契约保持浏览器可读v0.4.0 patch。8.remix test测试编排remix test在 v0.4.0 获得完整参数解析、帮助、校验与 shell 补全并委托类型化 runner 选项给remix-run/test/cli同时保留位置 glob、重复 flag、别名、配置优先级、覆盖率、过滤与 watch 行为见 #11623。测试相关设置均可从remix.json#test读取见 2.2 节。三个测试类型server/browser/e2e可组合运行覆盖三种池forks/threads与四种 reporterspec/files/tap/dot。仓库内各 demo 均有对应测试资产例如 demos/bookstore/app/db.test.ts、demos/bookstore/app/router.test.ts 与端到端 demos/bookstore/app/app.test.e2e.ts。v0.3.1 patch 修正了帮助文本语法高亮路径参数如./my-remix-app中的连字符不再被误标为单字符 flag见 #11409。9.remix completion与其他命令remix completion生成 shell 补全。v0.3.0 patch 修复了--分隔符在全局选项后仍可用、可在 shell 名后请求补全帮助、remix test补全不再重复--help等边界情况。remix version/remix --version/-v输出 Remix 版本runRemix({ remixVersion })可覆盖。remix help输出 CLI 帮助。10. 项目结构与破坏性变更速查升级指南10.1 v0.3.0app/controllers→app/actionsBREAKING脚手架、remix doctor与remix routes统一使用app/actions下的控制器文件把app/controllers改名为app/actions根路由叶子文件合并进app/actions/controller.tsxcontroller.tsx/controller.ts及controller.test.ts/controller.test.tsx原home、about、uploads等成为actions对象条目嵌套路由按路由映射键命名目录routes.auth→app/actions/auth/controller.tsxroutes.account.settings→app/actions/account/settings/controller.tsxrouter.map()只映射传入 route map 的直接叶子路由嵌套映射需显式注册router.map(routes, rootController) router.map(routes.auth, authController) router.map(routes.account, accountController) router.map(routes.account.settings, accountSettingsController)控制器中间件只作用于该控制器直接持有的 action不会保护嵌套路由映射注册的控制器——需要时把中间件复制到每个需要它的控制器如account/controller.tsx与account/settings/controller.tsx迁移后删除每个控制器中多余的嵌套键与未知 action 键actions对象应精确对应router.map()传入的 route map 直接叶子键路由局部页面、schema、辅助函数与测试保留在所属控制器旁跨路由共享 UI 移到app/ui。10.2 其他变更v0.2.0移除remix skills默认服务器改用remix/node-servev0.3.0 又改为remix/node-fetch-server避开原生 uWebSockets.js 传输。v0.4.0--config语义变更见 2.1旧remix-test.config.*自动发现移除。11. 源码地图继续深入关注点路径CLI 入口与调度packages/cli/src/lib/cli.ts配置解析与校验packages/cli/src/lib/remix-config.tsJSON Schemapackages/cli/schema/remix.json数据库命令packages/cli/src/lib/commands/db.ts、packages/cli/src/lib/database-command.ts资源审计packages/cli/src/lib/commands/assets.ts项目体检packages/cli/src/lib/commands/doctor.ts、packages/cli/src/lib/doctor/路由检视packages/cli/src/lib/commands/routes.ts脚手架packages/cli/src/lib/commands/new.ts、template/bookstore 实战示例demos/bookstore/remix.json、demos/bookstore/db/seed.sqlpackages/cli自身以remix test --concurrency 1作为测试脚本其commands/*.test.ts、remix-config.test.ts、parse-args.test.ts、controller-ownership.test.ts等测试文件见 packages/cli/src/lib/覆盖了本文所述的大部分行为是验证命令语义的第一手参考。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Remix CLI 完全指南：从 `remix new` 脚手架到数据库迁移、静态资源审计与测试编排
Remix CLI 完全指南从remix new脚手架到数据库迁移、静态资源审计与测试编排【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix导读本文以packages/cli/CHANGELOG.md为骨架系统梳理 Remix CLIremix-run/cli从 v0.1.0 到 v0.6.0 的核心能力演进remix new项目脚手架、remix doctor项目体检、remix routes路由树检视、remix db数据库命令族migrate / rollback / wipe / seed / reset / status、remix assets静态资源审计、remix test测试编排、remix.json统一配置与remix completion补全以及runRemix()可编程 CLI API。结合packages/cli/src下的源码实现与demos/bookstore真实示例你将掌握这些命令的完整参数、底层执行链路与配置优先级规则可直接落地到日常开发流程。1. CLI 包定位与运行前提remix-run/cli是 Remix 的命令行界面包v0.1.0 首次发布即提供公共的runRemix()API 以及项目脚手架、健康检查与修复、路由检视、测试运行四大类命令。用户日常敲的remix可执行文件由remix包提供remix-run/cli则暴露程序化 API源码入口。运行前提见 packages/cli/package.jsonNode.js 版本 24.3.0模块系统type: module使用 ESM依赖remix-run/assets、remix-run/data-table*sqlite / postgres / mysql、remix-run/terminal、remix-run/test以及jsonc-parser与semver。runRemix(argv, options)是唯一入口解析argv、调度到对应子命令、返回进程退出码。options支持cwd默认process.cwd()与remixVersion覆盖。典型用法import { runRemix } from remix-run/cli let exitCode await runRemix(process.argv.slice(2)) process.exit(exitCode)入口实现位于 packages/cli/src/lib/cli.ts先剥离开头的--分隔符再抽取全局选项--no-color、--config path/--configpath随后按子命令名调度到new、completion、assets、doctor、db、routes、test、version、help。命令实现全部懒加载await import(...)v0.2.0 的 patch 说明这一设计可避免无关命令在启动时加载可选依赖。全局选项说明选项含义--config path指定remix.json配置文件路径替换自动发现--no-color禁用终端颜色输出--分隔符其后参数不再解析为全局选项2.remix.json统一配置文件v0.4.0 引入v0.4.0 引入可选的静态remix.json配置文件覆盖数据库适配器、迁移与种子、remix test全部设置、remix doctor的 strict 模式。解析器对 JSONC 语法宽容支持注释与尾随逗号自动剥离 BOM见 remix-config.ts并使用jsonc-parser做树解析与精确的行/列错误定位。2.1 配置加载与优先级自动发现loadConfig(from)从给定目录默认process.cwd()向上查找最近的remix.json传入文件路径时直接读取该文件remix-config.ts。数据库命令从项目子目录执行也能找到最近的配置。优先级显式 flag 与位置参数 配置文件值 默认值。负向 flag--no-strict、--no-watch、--no-coverage、--no-quiet、--no-browser.open、--no-browser.echo可覆盖配置中的true。变更注意--config原先的测试专用含义与remix-test.config.ts/.js自动发现已被移除相关配置迁移至remix.json#test。2.2 配置结构RemixConfig顶层键为assets、db、doctor、test另有$schema指向编辑器校验用 JSON Schema。源码 remix-config.ts 与 Schema packages/cli/schema/remix.json 双源一致未知属性会直接报错Unknown property属于严格校验。assets段键类型说明allowFiles必填string[]允许被浏览器访问的文件路径与 globbasePath必填string静态资源公开 URL 前缀rootDirstring资源文件根目录相对本配置文件解析默认.allowPackagesstring[]允许通过包名暴露文件及其依赖的包denyFilesstring[]禁止被访问的文件路径与 globmountsRecordstring,string以 basePath 相对 URL 为键、目录为值的挂载表files.extensionsstring[]无需脚本/样式编译即可直接服务的附加文件扩展名db段adapter为必填三选一{ db: { adapter: { type: sqlite, filename: ./db/app.sqlite, // 或 { env: DB_PATH, default: ./db/app.sqlite } foreignKeys: true, // 可选 busyTimeout: 5000 // 可选非负整数毫秒 }, migrations: { directory: ./db/migrations, // 必填 journalTable: _remix_migrations // 可选迁移日志表名 }, seed: ./db/seed.sql // 可选 } }其他适配器remix-config.tsPostgreSQLtype: postgresconnectionString字符串或{env, default}可选maintenanceDatabase维护库用于建库/删库、template建库模板。MySQLtype: mysqluri字符串或{env, default}可选characterSet、collation。dbString支持环境变量间接引用{ env: DATABASE_URL, default: ... }。解析时已设置但为空的 env 视作未设置会回退到 defaultdatabase-command.ts。sqlite 的filename允许:memory:内存库配置中的相对路径以配置文件目录为基准解析而--connection-env覆盖时相对路径以命令调用目录为基准db.ts避免静默重定向。doctor段{ strict: true }存在 warning 级 findings 时remix doctor以退出码 1 结束。test段键类型说明files/browserFiles/e2eFilesstring[]各类型测试文件 globexcludestring[]排除 globonlystring[]按完整测试名聚焦的正则支持/re/flags字面量非法正则报错concurrencyinteger ≥ 1并发 worker 上限poolforks|threadsserver/e2e 测试 worker 池reporterspec|files|tap|dot输出格式quietboolean是否省略 skipped 测试输出setupstring导出globalSetup/globalTeardown的模块type[server,browser,e2e]运行的测试类型watchboolean文件变更自动重跑coverageobjectenabled、include/excludeglob、dir输出目录、branches/functions/lines/statements最低覆盖率百分比playwrightobjectconfigFile、projectsPlaywright 项目名、open结束后保留浏览器、echo回显浏览器 console 到 stdout所有 glob 均相对配置文件目录解析再转换为相对cwd的 POSIX 路径setup、dir、configFile等路径键也按配置目录解析remix-config.ts。3.remix new项目脚手架remix new target-dir [--app-name name] [--force]在目标目录创建新 Remix 项目new.ts。--app-name覆盖显示名--force允许写入非空目录。执行过程分三阶段并带进度输出Prepare target directory→Generate scaffold files→Finalize package.json。CHANGELOG 记录了模板的持续演进v0.2.0默认服务器改为remix/node-serve移除remix skills命令BREAKING。v0.3.0默认模板只含单个 home 路由共享 HTML 渲染迁移到中间件app/middleware/render.tsx通过请求上下文context.render读取模板新增静态资源服务public/、Remix favicon 与共享文档壳。v0.3.2/0.3.4剥离 Remix 仓库特定逻辑生产环境以NODE_ENVproduction启动、压缩浏览器资源、使用 dev server watcher而非 asset server watcher、客户端与服务端都能解析 frames脚手架包含模板.gitignoreremix doctor --fix不得通过符号链接在项目根之外创建/更新文件见 #11532。v0.4.0新项目自带npm run hmr与hmr.ts运行器。v0.5.0默认模板为客户端入口提供 preloads。仓库根目录的 template 目录即对应脚手架产物结构app/actions/、app/assets.ts、app/router.ts、app/routes.ts、hmr.ts、server.ts等。模板随包发布通过 scripts/sync-cli-template.ts 在prepack时同步。4.remix db数据库命令族v0.4.0 新增remix db系列命令v0.6.0 补齐回滚能力。命令矩阵如下帮助文本见 db.ts子命令作用特殊 flagremix db wipe --force清空当前数据库整库销毁--force必填remix db migrate [--to m]应用迁移--to仅向前推进到指定迁移--toremix db rollback [--step N \| --to m] [--dry-run]从新到旧回滚默认回滚 1 步--step/--to互斥、--dry-runremix db status展示迁移状态—remix db seed执行 SQL 种子文件--seed pathremix db reset --force清库 迁移 种子--force必填公共选项--migrations path迁移目录、--journal-table name日志表、--connection-env name从环境变量读取连接、--seed path。回滚语义v0.6.0 新增Database.migrate()早已接受direction、to、step、dryRun但 CLI 从未传递——因此此前迁移的down.sql在remix db下不可达--to只能限制向前进度。rollback修复了这条链路--step count默认 1从最新开始回滚 N 个迁移--to migration含该迁移在内回滚至它--dry-run只报告将回滚的内容不实际执行--step与--to互斥--step必须是正整数db.ts。4.1 执行链路解析parseDbCommandArgs按子命令分别解析db.tswipe/reset缺--force直接抛dbForceRequired。配置解析无--config时向上查找remix.json找不到抛remixConfigNotFoundconfig.db缺失抛dbConfigRequireddb.ts。计划合成resolveDatabaseCommandPlan将 flag 覆盖合入配置并校验 migrate/rollback/status/reset 需要迁移目录、seed 需要种子文件db.ts。适配器实例化按adapter.type懒加载remix-run/data-table-sqlite/postgres/mysql之一db.ts。sqlite 会自动创建父目录并支持:memory:postgres 支持maintenanceDatabase与templatemysql 强制multipleStatements: true以支持种子多语句。执行通过remix-run/data-table/cli的runRemixDb完成迁移与种子分别经loadMigrations、loadSeed加载db.ts。数据库连接在命令结束后统一close()若命令与关闭双双失败则抛出AggregateError。4.2 真实示例bookstoredemos/bookstore/remix.json 展示最小可用配置sqlite 迁移目录 种子{ $schema: node_modules/remix/schema/remix.json, db: { adapter: { type: sqlite, filename: ./db/bookstore.sqlite, foreignKeys: true }, migrations: { directory: ./db/migrations }, seed: ./db/seed.sql }, test: { playwright: { configFile: ./playwright.config.ts } } }迁移以时间戳_名称/up.sqldown.sql目录形式组织例如 demos/bookstore/db/migrations/20260228090000_create_bookstore_schema/up.sql 创建books、users、orders、order_items等表同名目录下的 down.sql 按依赖逆序drop table先删外键引用方password_reset_tokens、order_items、orders再删users、books。种子文件 demos/bookstore/db/seed.sql 使用幂等insert or ignore into语句可安全重复执行。典型工作流remix db migrate # 应用全部迁移 remix db status # 查看迁移状态 remix db seed # 写入种子数据 remix db rollback --step 1 # 回滚最近一个迁移 remix db rollback --to 20260228090000_create_bookstore_schema --dry-run remix db reset --force # 清库 迁移 种子5.remix doctor项目健康检查与自动修复remix doctor [--json] [--strict] [--no-strict] [--fix]检查项目环境与 Remix 应用约定doctor.ts--json以 JSON 输出 findings--strict存在 warning 级 findings 时退出码为 1--no-strict反向覆盖--fix应用低风险自动修复。strict 取值逻辑先取remix.json#doctor.strict默认false再按 argv 中出现的--strict/--no-strict顺序覆盖doctor.ts。实现细节v0.4.0 patchaction 检查被限定在app/routes.ts所需的目录与控制器路径app/actions下无关文件/目录被忽略--fix不再生成 action 控制器源码见 packages/cli/src/lib/doctor/ 下的controllers.ts、controller-findings.ts、fixes.ts。v0.3.4 起--fix在路径穿越符号链接时会阻止在项目根之外创建/更新文件见 #11532。6.remix routes路由树检视remix routes [--json | --table] [--no-headers] [--verbose]输出当前应用的路由树routes.ts--json输出规范化路由树 JSON--table扁平表格列Route / Method / Path / Owner--no-headers配合--table省略表头--verbose树/表中显示完整 owner 路径否则省略app/actions/前缀。flag 互斥校验--json不能与--table、--verbose组合--no-headers必须搭配--table。路由树由 route-map.ts 的loadRouteMap在 worker 中加载owner 缺失[missing]的节点以红色渲染便于一眼发现路由指向不存在的控制器。v0.3.0 起路由归属统一为app/actions目录结构见下节。7.remix assets静态资源审计v0.6.0 新增remix assets列出所有浏览器可达资源输出稳定的URL → 文件映射remix assets inspect url-or-file针对单个 URL 或文件路径解释其映射关系、文件类型、访问规则与状态assets.tsremix assets remix assets inspect /assets/app/actions/public/entry.ts remix assets inspect app/actions/public/entry.ts实现上命令加载remix.json#assets配置缺失抛assetsConfigRequired用createAssetServer({ ...config.assets, watch: false })以非监听模式实例化资源服务器来自remix-run/assets再分别调用getAssets()列表与getAssetDetails(input)详情最后close()释放资源。inspect输出包含Status、URL、File被拒绝时附带Denied by访问规则来源如denyFiles。配套变更新增共享的assets配置段并导出loadConfig脚手架把浏览器可达源码放在app/内各 colocatedpublic/目录浏览器运行时入口为app/actions/public/entry.ts共享的app/routes.ts契约保持浏览器可读v0.4.0 patch。8.remix test测试编排remix test在 v0.4.0 获得完整参数解析、帮助、校验与 shell 补全并委托类型化 runner 选项给remix-run/test/cli同时保留位置 glob、重复 flag、别名、配置优先级、覆盖率、过滤与 watch 行为见 #11623。测试相关设置均可从remix.json#test读取见 2.2 节。三个测试类型server/browser/e2e可组合运行覆盖三种池forks/threads与四种 reporterspec/files/tap/dot。仓库内各 demo 均有对应测试资产例如 demos/bookstore/app/db.test.ts、demos/bookstore/app/router.test.ts 与端到端 demos/bookstore/app/app.test.e2e.ts。v0.3.1 patch 修正了帮助文本语法高亮路径参数如./my-remix-app中的连字符不再被误标为单字符 flag见 #11409。9.remix completion与其他命令remix completion生成 shell 补全。v0.3.0 patch 修复了--分隔符在全局选项后仍可用、可在 shell 名后请求补全帮助、remix test补全不再重复--help等边界情况。remix version/remix --version/-v输出 Remix 版本runRemix({ remixVersion })可覆盖。remix help输出 CLI 帮助。10. 项目结构与破坏性变更速查升级指南10.1 v0.3.0app/controllers→app/actionsBREAKING脚手架、remix doctor与remix routes统一使用app/actions下的控制器文件把app/controllers改名为app/actions根路由叶子文件合并进app/actions/controller.tsxcontroller.tsx/controller.ts及controller.test.ts/controller.test.tsx原home、about、uploads等成为actions对象条目嵌套路由按路由映射键命名目录routes.auth→app/actions/auth/controller.tsxroutes.account.settings→app/actions/account/settings/controller.tsxrouter.map()只映射传入 route map 的直接叶子路由嵌套映射需显式注册router.map(routes, rootController) router.map(routes.auth, authController) router.map(routes.account, accountController) router.map(routes.account.settings, accountSettingsController)控制器中间件只作用于该控制器直接持有的 action不会保护嵌套路由映射注册的控制器——需要时把中间件复制到每个需要它的控制器如account/controller.tsx与account/settings/controller.tsx迁移后删除每个控制器中多余的嵌套键与未知 action 键actions对象应精确对应router.map()传入的 route map 直接叶子键路由局部页面、schema、辅助函数与测试保留在所属控制器旁跨路由共享 UI 移到app/ui。10.2 其他变更v0.2.0移除remix skills默认服务器改用remix/node-servev0.3.0 又改为remix/node-fetch-server避开原生 uWebSockets.js 传输。v0.4.0--config语义变更见 2.1旧remix-test.config.*自动发现移除。11. 源码地图继续深入关注点路径CLI 入口与调度packages/cli/src/lib/cli.ts配置解析与校验packages/cli/src/lib/remix-config.tsJSON Schemapackages/cli/schema/remix.json数据库命令packages/cli/src/lib/commands/db.ts、packages/cli/src/lib/database-command.ts资源审计packages/cli/src/lib/commands/assets.ts项目体检packages/cli/src/lib/commands/doctor.ts、packages/cli/src/lib/doctor/路由检视packages/cli/src/lib/commands/routes.ts脚手架packages/cli/src/lib/commands/new.ts、template/bookstore 实战示例demos/bookstore/remix.json、demos/bookstore/db/seed.sqlpackages/cli自身以remix test --concurrency 1作为测试脚本其commands/*.test.ts、remix-config.test.ts、parse-args.test.ts、controller-ownership.test.ts等测试文件见 packages/cli/src/lib/覆盖了本文所述的大部分行为是验证命令语义的第一手参考。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考