Graphweaver 2.24.1 常用 CLI 命令与工具详解
Graphweaver 2.24.1 的 9 个 CLI 子命令逐参数实测篇：init/import/build/build-types/print-schema/start/watch/init-auth/analyse 的参数定义与真实回显，import 内省的 MikroORM 版本排障实录，print-schema 完整执行链路，以及 tsc not found、@babel/runtime 报错、全局与项目内 CLI 调用边界等五则实测排障。
Graphweaver 2.24.1 常用 CLI 命令与工具详解
目标：逐参数讲清 Graphweaver 2.24.1 的 9 个 CLI 子命令——参数定义、实测回显、执行链路与排障实录。全部命令在 Ubuntu 24.04 服务器实跑（版本基线
graphweaver --version→ 2.24.1），前置安装与 systemd 托管见《Ubuntu 24.04 安装 Graphweaver 2.24.1 指南》（https://www.quzuo.net/document/ttTs2hhrdek9），命令背后的环境变量语义见[《Graphweaver 2.24.1 配置参数详解》](https://www.quzuo.net/document/ylmKf3FKzYcO)（https://www.quzuo.net/document/ylmKf3FKzYcO）。
一、CLI 总览
graphweaver 主帮助实测回显（graphweaver 不带参数即输出）：
graphweaver
Commands:
graphweaver init Create a graphweaver project in various ways.
graphweaver import [source] Inspect a data source and then import its
entities.
graphweaver analyse [target] Instruments your graphweaver project in
various ways. [aliases: analyze, a]
graphweaver build [environment] Builds your graphweaver project for
deployment. [aliases: b]
graphweaver build-types Builds your Graphweaver types.
graphweaver print-schema Prints the schema to stdout or to a file.
graphweaver start [environment] Runs a development version of the project
locally. [aliases: s]
graphweaver watch [environment] Runs a development version of the project
locally and watches files for changes.
[aliases: w]
graphweaver init-auth [method] Initialise Graphweaver with a primary
authentication method. [aliases: auth]
Options:
--version Show version number [boolean]
--help Show help [boolean]
9 个子命令、6 个短别名（a/b/s/w/auth/analyze），全局项只有 --version 与 --help。按使用阶段分组：
| 阶段 | 命令 | 一句话定位 |
|---|---|---|
| 脚手架 | init | 生成项目骨架 |
| 数据接入 | import | 内省既有库反推实体 |
| 开发 | start / watch | 前后端双进程开发服务 |
| 构建 | build / build-types / print-schema | 生产产物 / 前端类型 / Schema 透出 |
| 认证与治理 | init-auth / analyse | 认证初始化 / bundle 分析 |
调用方式先给结论（排障实录见第十节）：项目目录内一律经 npm scripts 或 pnpm exec 调用，全局 CLI 只用于 init 与版本探针。
二、init：项目脚手架
参数定义（graphweaver init --help 实测）：
graphweaver init
Create a graphweaver project in various ways.
Options:
--version Show version number [boolean]
--help Show help [boolean]
--name The name of this project. [string]
--backend Specify one or more data sources.
[array] [choices: "postgres", "mssql", "mysql", "rest", "sqlite"]
--useVersion Specify a version of Graphweaver to use. [string]
三个要点：--backend 是 array 类型（一次可勾选多个后端，交互模式用空格多选）；--useVersion 可钉住脚手架版本；不带参数直接跑 init 则进入交互问答。
非交互实测（sqlite 后端，项目名 gwdemo）：
graphweaver init --name gwdemo --backend sqlite
Initialising a new Graphweaver project...
Project Name: gwdemo
Backends: Sqlite
All Done!
Make sure you cd to the new project directory, then run pnpm install and pnpm start.
产物五件套与 package.json 的 devDependencies 实测：
.gitignore README.md package.json src/ tsconfig.json
"devDependencies": {
"@types/node": "26.6.1",
"graphweaver": "2.24.1",
"typescript": "7.0.2"
}
脚手架把 graphweaver 与 typescript 钉进 devDependencies——这正是第十节"项目内 CLI"路线的物质基础。
三、import：数据库内省导入
graphweaver import [source] 直连既有数据库，读取表结构与外键反推实体代码。实测以 PostgreSQL 源执行，交互确认连接参数后进入内省阶段（日志实测，节选）：
Importing data source...
Source: postgresql
Database Name: gwdemo
Database Host: 10.89.74.2
Database Port: 5432
Database User: gwuser
- Introspecting...
{"level":30,"name":"graphweaver","connectionParams":{"host":"10.89.74.2","port":5432,"dbName":"gwdemo","user":"gwuser"},"msg":"Connecting to database using MikroORM. Note: connectionParams have password removed for security."}
实测排障：内省阶段报错中断（完整错误，ANSI 色码已剔除）：
Got error during introspection:
Error: Bad @mikro-orm/knex version 6.6.2.
All official @mikro-orm/* packages need to have the exact same version as @mikro-orm/core (6.6.17).
Only exceptions are packages that don't live in the 'mikro-orm' repository: nestjs, sql-highlighter, mongo-highlighter.
Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?
IntrospectionError: Bad @mikro-orm/knex version 6.6.2.
...
title: 'Warning: Unable to connect to database.',
type: 'IntrospectionError'
与配置篇 4.1 节同源的版本校验问题，但形态不同：这里报的是项目内依赖 knex 6.6.2 与 core 6.6.17 不一致（内省用项目 node_modules 的 MikroORM）。修复用 pnpm 对齐：
pnpm up @mikro-orm/knex @mikro-orm/core @mikro-orm/postgresql
实测回显（节选）：
dependencies:
- @mikro-orm/core 6.6.2
+ @mikro-orm/core 6.6.17 (7.2.5 is available)
- @mikro-orm/knex 6.6.2
+ @mikro-orm/knex 6.6.17
- @mikro-orm/postgresql 6.6.2
+ @mikro-orm/postgresql 6.6.17 (7.2.5 is available)
Done in 5.2s using pnpm v9.15.9
对齐后重跑 import 即可走通内省与实体生成。经验：import 失败先查项目内 @mikro-orm/* 三件套版本一致性，再用 pnpm up 收敛。
四、build：生产构建
参数定义（graphweaver build --help 实测）：
graphweaver build [environment]
Builds your graphweaver project for deployment.
Positionals:
environment Choose whether you want to build the backend, frontend, or both.
[string] [choices: "backend", "frontend", "all"] [default: "all"]
Options:
--version Show version number [boolean]
--help Show help [boolean]
--adminUiBase Specify the base path for the Admin UI [string] [default: "/"]
执行链路实测（pnpm build 于 PostgreSQL 项目，关键步骤行）：
Building backend...
Appending start command.
Checking Typescript types...
Backend Build Finished!
Generating Types...
Typescript types passed.
随后 Vite 完成前端构建（尾部 ✓ built in 5.20s + Build complete!）。产物：dist/backend/index.js 单文件 bundle（node dist/backend/index.js 即跑，systemd 托管见安装篇第九节）；Vite 产物超过 500 kB 时的 chunk 拆分警告属常规提示，不阻断构建。
--adminUiBase 用于把 Admin UI 挂到子路径（如 /admin），多应用共享域名时才需要。
五、start / watch：开发服务
参数定义（graphweaver start --help 实测）：
graphweaver start [environment]
Runs a development version of the project locally.
Positionals:
environment Choose whether you want to run the backend, frontend, or both.
[string] [choices: "backend", "frontend", "all"] [default: "all"]
Options:
--version Show version number [boolean]
--help Show help [boolean]
--host Specify a host to listen on e.g. --host 0.0.0.0 [string]
--port Specify a base port to listen on. Frontend will start on this port,
and backend will start on port+1 [number] [default: 9000]
端口语义是本命令的核心：前端占 --port（默认 9000），后端自动 +1（9001）——开发模式 Admin UI 与 API 双端口的由来。启动成功日志尾部实测：
The Graphweaver server has started. 😀😀
The GraphQL API is available at http://localhost:9001/
/Admin UI is available at http://localhost:9000/ 🚀
If you are new here, start with Admin UI.
远程访问加 pnpm start -- --host 0.0.0.0；environment 位置参数可只起 backend 或 frontend（调 API 时省掉 Vite）。watch 与 start 同参数别名 w，差异仅在文件变更热重启。别名 s 同 start。
六、print-schema：Schema 透出
参数定义（graphweaver print-schema --help 实测）：
graphweaver print-schema
Prints the schema to stdout or to a file.
Options:
--version Show version number [boolean]
--help Show help [boolean]
-o, --output Specify the output file. [string]
-o 落文件、缺省打 stdout。执行前会完整重走一次后端构建 + 类型检查，实测回显（pnpm exec graphweaver print-schema，sqlite 项目）：
Printing schema...
Building backend....
- Building ./src/backend/index => dist/backend/index.js
The following modules are external and won't be bundled:
Set(21) {
'./lib/migrations/migrate/Migrator.js',
'tedious', 'mysql', 'mysql2', 'pg', 'pg-native', 'pg-query-stream',
'oracle', 'sqlite3', 'better-sqlite3', 'oracledb', 'libsql', 'mariadb',
'bun:ffi', 'mock-aws-s3', 'nock', 'aws-sdk', '@aws-sdk/*', 'mariadb/callback'
}
If you want to bundle any of these, you can add them as a dependency in your package.json file.
Lambda handler detected. No changes needed.
Checking Typescript types... /srv/gwdemo
Backend Build Finished!
{"level":30,"name":"graphweaver","msg":"Graphweaver handler called"}
schema {
query: Query
}
type AdminUiEntityAttributeMetadata {
isReadOnly: Boolean
exportPageSize: Float
输出即当前项目完整 GraphQL SDL（含实体类型与 AdminUi 元数据类型、Sort/AggregationType 等 enum），尾部一行 Typescript types passed.。两点解读：
- 外部模块清单（Set(21)）：esbuild 标记为 external 的数据库驱动，按需装进 package.json 才会打进 bundle——换数据源后 print-schema 的这行清单是排查依据；
- Lambda handler detected：构建器识别到部署目标为独立服务器形态并确认无需改造，print-schema 复用了同一构建管线。
典型用途：pnpm exec graphweaver print-schema -o schema.graphql 导出 SDL 供代码生成、diff 审查或网关注册。
七、build-types：前端类型生成
无子参数（仅全局 --version/--help）。实测（pnpm exec graphweaver build-types）：
✔ Generate outputs
Generating types in the following paths:
/srv/gwdemo/src/frontend
Types generated.
产物落在项目 src/frontend，供 Admin UI 自定义页面与前端应用复用实体类型。build 主流程的 Generating Types... 步骤内部即调用了同一能力。
八、init-auth：认证初始化
参数定义（graphweaver init-auth --help 实测）：
graphweaver init-auth [method]
Initialise Graphweaver with a primary authentication method.
Positionals:
method The primary authentication method to use.
[string] [choices: "password", "api-key", "magic-link"] [default: "password"]
Options:
--version Show version number [boolean]
--help Show help [boolean]
--source Specify the database type.
[string] [choices: "mysql", "postgresql", "sqlite"]
--database Specify the database name. [string]
--host Specify the database server hostname. [string]
--port Specify the database server port. [number]
--password Specify the database server password. [string]
--user Specify the database server user. [string]
三种主认证方式：password（默认）、api-key、magic-link（别名 auth）。--source 及后续五参是认证数据表的落库位置——在既有库上建用户/凭据表，参数语义与 DATABASE_* 环境变量一一对应。选型篇对认证能力（2FA、Auth0、Cognito 等扩展方式）有横向说明。
九、analyse：bundle 分析
参数定义（graphweaver analyse --help 实测）：
graphweaver analyse [target]
Instruments your graphweaver project in various ways.
Positionals:
target The thing to analyse. [string] [choices: "bundle"] [default: "bundle"]
Options:
--version Show version number [boolean]
--help Show help [boolean]
2.24.1 中 target 仅支持 bundle（别名 analyze/a），对构建产物做插桩分析，属低频治理工具；常规交付链路不经过它。
十、实测排障汇总
1. tsc: not found → Typescript types failed check.（print-schema/build-types/build 高频坑）
绕过 npm scripts 直接跑 CLI（无论全局 graphweaver 还是项目内 ./node_modules/.bin/graphweaver）时报：
/bin/sh: 1: tsc: not found
Error: Typescript types failed check.
根因：构建器以 sh -c tsc 执行类型检查，该子 shell 的 PATH 不含项目 node_modules/.bin。修复：经 npm scripts 或 pnpm exec 调用（pnpm 会注入 .bin 到 PATH），实测 pnpm exec graphweaver print-schema 一次通过。全局 CLI 只保留 init/--version 两个用途。
2. 全局 CLI 在项目内跑 start 报 Missing "./regenerator" specifier in "@babel/runtime"
同源问题：全局 CLI 解析依赖时命中自身依赖树，与项目 pnpm 布局冲突，Vite 前端进程起不来。项目内一律 pnpm start。
3. import 内省报 Bad @mikro-orm/knex version ...
见第三节实录：项目内 pnpm up 对齐三件套后重跑。
4. 生产 bundle 启动报 Bad @mikro-orm/knex version 6.6.17 ... @mikro-orm/core (0.1.0)
bundle 内版本探测失真所致，运行环境注入 MIKRO_ORM_ALLOW_VERSION_MISMATCH=1（配置篇 4.1 节）。
5. 版本探针与免安装执行
npx -y graphweaver@2.24.1 --version # → 2.24.1
CI 冒烟或临时验证用 npx 直跑，免全局安装；--useVersion 参数（init）可在脚手架阶段钉版本。
十一、参考链接
- 安装与 systemd 托管：《Ubuntu 24.04 安装 Graphweaver 2.24.1 指南》 https://www.quzuo.net/document/ttTs2hhrdek9
- 环境变量与配置注入：《Graphweaver 2.24.1 配置参数详解》 https://www.quzuo.net/document/ylmKf3FKzYcO
- 定位、架构与选型：《Graphweaver 2.24.1 介绍与选型指南》 https://www.quzuo.net/document/iU0iIHHNlNsS
- Graphweaver 官方文档：https://graphweaver.com/docs （查询日期 2026-10-24）
- npm 包 graphweaver（CLI）：https://www.npmjs.com/package/graphweaver （2.24.1，2026-10-24 实查）