nocobase-create-app

创建 NocoBase 3 应用

此 Skill 会创建、配置并在本地运行一个新项目：用于开发的源代码，而不是可部署的构建版应用。它不介绍如何开发应用：应用一旦创建完成，就由其自己的 AGENTS.md 和 .agents/skills/ 接管。这些文件与已安装的版本相匹配，而此 Skill 不匹配，因此两者不同时，以它们为准。

开始之前

• 如果工作目录中已有 NocoBase 应用——其中包含带有 nocobase 字段的 package.json，且旁边有 AGENTS.md——请勿使用此 Skill。请阅读该 AGENTS.md 并从中继续操作。

• NocoBase 3 使用 pnpm create @nocobase/app@beta 创建。切勿改用 NocoBase 2 的说明或 nb CLI，即使找不到软件包也不例外；请参阅故障排除。

• 确认用户的请求适用于此 Skill。项目是供他人修改、在本地开发的源代码；安装则是已构建、仅运行的 NocoBase，通常用于生产环境，属于 nocobase-app-installer：

  用户请求	Skill
  安装、创建、设置或试用 NocoBase，以进行开发	此 Skill
  将应用部署到生产环境或服务器	nocobase-app-installer，--archive

  将部署请求交给 nocobase-app-installer 处理，并在此处停止。

• 在 Windows 上，请在 WSL 中操作。以下命令假定使用 Bash 等 POSIX Shell；子 Shell 和内联环境变量在 PowerShell 或 cmd 中无法正常工作。

• 检查 node --version（24 或更高版本）和 pnpm --version（11）。如果缺少其中任一工具或版本不匹配，请先停止，不要创建任何内容，并告知用户：

  • 缺少哪个工具，或检测到哪个版本，以及所需版本；
  • 在其操作系统上安装该工具的命令，优先使用其已在使用的版本管理器，例如 nvm install 24 或 fnm install 24；安装 pnpm 可使用 corepack enable && corepack prepare pnpm@11 --activate 或 npm install -g pnpm@11；
  • 之后打开新的 Shell，以便新版本出现在 PATH 中。

  除非用户提出要求，否则不要自行安装这些工具。继续操作前，请再次检查两个版本。

• 在用户指定的目录中创建应用；如果当前目录为空，则在当前目录中创建。目录必须是新目录或空目录，且其名称将成为应用名称：必须以小写字母或数字开头，且只能包含小写字母、数字、点、短横线和下划线。如果目录非空或名称无效，请让用户另选一个目录。切勿覆盖文件，也不要先创建嵌套项目再将其文件移出。

创建

pnpm create @nocobase/app@beta 不接受 . 作为名称。请在父目录中使用目标目录的名称运行它，这会将文件直接生成到该目录中：

(cd <parent-directory> && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 npm_config_registry="${NOCOBASE_REGISTRY:-https://registry.npmjs.org}" pnpm create @nocobase/app@beta <name> --template-tag=beta --json)

• NocoBase 3 的软件包（包括 @nocobase/create-app）发布在公共 npm 注册表中。该命令仅在此进程中设置该注册表，同时允许使用 NOCOBASE_REGISTRY 选择私有注册表或尚未发布的本地快照；create-app 会对模板和依赖项安装使用同一个注册表，并且只会在项目的 .npmrc 中记录非公共注册表的覆盖设置。不要更改用户的 pnpm 配置。
• 创建工具（@nocobase/app@beta）和模板（--template-tag=beta）都要使用 beta 通道；只选择工具并不会选择模板通道。如果无法解析 beta，不要回退到 latest。用户明确指定的版本或本地快照优先。
• 只有在 shell 指向其他注册表（例如尚未发布的快照）时，才设置 NOCOBASE_REGISTRY；create-app 也会读取它。
• PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 允许 pnpm 安装几分钟前发布的版本。
• --json 不会提示用户。它会在 stdout 上打印一份 JSON 文档，并在 stderr 上打印进度，因此只解析 stdout。这是每个 pnpm nocobase … --json 命令打印的统一格式：ok 表示创建是否成功，result 包含生成的内容；失败时，error.code、error.message 和 error.details 会说明操作在哪一步停止。create-app 0.1.0-beta.23 及更早版本则会打印扁平结果，其中 status 为 success 或 error，而 stage、message、directory 和 nextCommands 位于顶层；请读取相同字段。
• 默认模板用于开发应用，无需添加 --template 标志；请保留 --template-tag=beta。如果用户想先通过示例功能探索 NocoBase，请添加 --template=examples。

在进行其他操作之前，先查看结果：

结果	操作
ok: true（扁平结果中为 status: "success"）	继续执行以下步骤。报告所有 warnings。
INVALID_USAGE，阶段为 input（退出码 2）	修正参数。未创建任何内容。
TEMPLATE_DOWNLOAD_FAILED，阶段为 download	检查网络和已配置的注册表。未创建任何内容。
INSTALL_FAILED，阶段为 install	项目已存在。在项目目录中运行 pnpm install 重试，然后继续执行配置步骤。不要再次创建项目。
DRIVER_VERIFICATION_FAILED，阶段为 verify	即使经过重新构建，SQLite 驱动程序的原生插件仍未能加载。报告相关消息；其中会指出原因。
NODE_UNSUPPORTED	Node.js 版本低于 24。请用户升级；未执行任何操作。
其他任何失败	向用户报告相关消息和目录。

阶段位于 error.details.stage，目录位于 error.details.directory；在扁平结果中，它们分别位于 stage 和 directory。

重试时绝不要删除该目录。

配置

从这里开始，在应用目录中操作。现在读取其 AGENTS.md：它是在本次会话开始后出现的，因此可能尚未加载。

result.nextCommands 用于将应用配置为使用 SQLite，然后启动应用。如果重试安装后没有这些命令，它们依次是 pnpm nocobase config init、pnpm nocobase config check，然后是 pnpm dev。除非用户已经指定数据库，否则运行这些命令前先询问用户想使用哪种数据库，并按照以下步骤进行调整：SQLite 以外的数据库需要安装驱动、指定 --dialect，并在 config init 和 config check 之间运行 config set。每个 pnpm nocobase config 命令都要传入 --json，并根据它打印的文档操作，而不能只看退出代码：ok 表示是否成功，result 包含生成的内容；失败时，error.code、error.suggestions 和 error.details 会说明下一步该怎么做。

1. 选择数据库。 使用用户指定的数据库，或先询问用户。SQLite 无需安装任何内容：模板已依赖其驱动。其他数据库则需先安装对应驱动，例如 pnpm add @nocobase/db-postgres@beta。
2. pnpm nocobase config init --dialect <dialect> --json 根据应用的 config.example.yml 生成 config.yml，并生成密钥。
   • 此命令不会安装任何内容。若缺少驱动，它不会写入任何内容，并会以 error.code DRIVER_MISSING 失败；error.suggestions[0].run 是用于安装该驱动的 pnpm add 命令。运行该命令，然后再次运行 config init。
   • 如果应用已经配置好，命令会报告 status: "success-noop"，因此重新运行此流程是安全的。
   • result.requiredSettings 列出仍为占位值的连接设置。
3. pnpm nocobase config set key=value … --json 设置每个 requiredSettings，例如 database.connections.main.host=db.internal。密码始终通过环境变量设置；请参阅下文“密钥”。
4. pnpm nocobase config check --json 必须通过后才能启动应用。此命令会加载配置但不会启动应用，并连接到数据库。失败时会返回 error.code CONFIG_INVALID，发现的问题位于 error.details.findings；每项都会指出对应的键，并在适用时提供要运行的 fix。应用修复后再次运行。

如需了解特定数据库的详情，请在应用目录中读取 .agents/skills/nocobase-app-development/references/database-connections.md。

如果 pnpm nocobase config init --help 显示该命令不存在，说明应用版本早于这些命令：请遵循其 AGENTS.md，不要按照本节操作。

启动

nextCommands 中最后一个命令 pnpm dev 不会退出。请在后台运行，并等待它打印 URL：只有应用准备就绪后才会打印 Local: 行，且 URL 会包含应用的路径，例如 /main/。请求该确切 URL，例如使用 curl -I，并确认收到成功响应后再报告成功。尚未配置的应用无法启动；请运行 pnpm nocobase config check --json 并按照其中的修复说明操作。

密钥

• 切勿在对话中询问密码，也不要将密码放在命令行上。请用户将密码设置到环境变量中，然后运行 pnpm nocobase config set --from-env database.connections.main.password=<VARIABLE> --json。
• 切勿打印 config.yml 或其中包含的任何密钥。
• 不要传入 --force、删除 config.yml 或删除数据库来使步骤通过。config init --force 会替换现有配置，仅在用户明确要求这样做时使用。

完成

告诉用户：

• 应用目录和 URL。
• 首个登录账号。该账号来自配置中的 users.initialAdmin：默认用户名为 nocobase（邮箱为 [email protected]），密码为 admin123。请读取该配置项，不要假定使用默认值；绝不要重复用户自行设置的密码，并提醒他们登录后更改默认密码。
• 服务由本次会话启动，会在会话结束时停止；如需再次启动，请在应用目录中运行 pnpm dev，可以在自己的终端或下一个会话中运行。
• 后续如何继续。应用的 AGENTS.md 和 Skills 是在本次会话开始后才出现的。有些 Agent 无需重启就能加载它们，有些则只会在会话启动时加载。请先确认适用情况，不要自行假定：
  • 本会话已加载（例如，可用 Skills 中包含应用的 nocobase-app-development Skill，且应用目录是本会话的工作目录）：告诉用户可以在本会话中继续，无需开启新会话。
  • 本会话未加载：告诉用户在应用目录中启动新的 Agent 会话，并准确说明操作方法。如果应用位于本会话的目录中，他们只需结束本会话，并在同一目录中启动新会话。否则，提供完整路径以及启动你自己的 Agent 所用的命令，例如 Claude Code 的 cd /work/my-app && claude。如果使用桌面客户端，则打开该目录作为项目，并启动新会话。
• 正在运行的应用首页已包含使用 Agent 进行开发的指南。请引导用户前往该页面了解下一步，而不要另行添加首个功能指南的链接。
• 之后如需部署到生产环境：应用自带的 nocobase-deployment Skill 会构建部署归档包，全局的 nocobase-app-installer Skill 会在运行应用的机器上安装它。用一行说明；现在不要启动部署。

保持交接简短：每个要点一行，命令和路径使用代码格式，并且只说明适用于该用户的情况。

如果 Skills 未加载，但用户仍想在本会话中继续工作，请勿依赖它们：遵循应用的 AGENTS.md，并直接读取相关的 .agents/skills/<name>/SKILL.md。

故障排查

症状	解决方法
创建时提示找不到 @nocobase/create-app（404）	检查包名和公共 npm 访问权限。对于私有快照，将 NOCOBASE_REGISTRY 设置为包含该包的注册表，然后重新运行 Create 命令。
创建时提示 Unknown option: 'registry'	pnpm create 不接受 --registry。按原样运行 Create 命令，并在 npm_config_registry 中指定注册表。
应用中提示找不到 @nocobase/...（404）	检查包名和版本。对于私有注册表，请确认项目的 .npmrc 中有匹配的 @nocobase:registry 条目。
没有匹配的版本，或最新版本被忽略	为该命令设置 PNPM_CONFIG_MINIMUM_RELEASE_AGE=0。
Could not locate the bindings file	没有适用于此平台的预编译 better-sqlite3 二进制文件。安装 C++ 工具链，在 pnpm-workspace.yaml 的 allowBuilds 下设置 better-sqlite3: true，然后运行 rm -rf node_modules && pnpm install。
提示无法同步 Skills	在应用中运行 pnpm nocobase skills sync。
pnpm dev 或 pnpm start 提示尚未配置	运行 pnpm nocobase config init --json，然后运行 pnpm nocobase config check --json，并按照结果操作。

应用使用指南请参阅 https://github.com/nocobase/nocobase/blob/v3-develop/docs/docs/en/capabilities/quick-start.md。