# @dotcms/create-app 中文文档

规范地址：https://npmcn.com/package/%40dotcms/create-app/

版本：26\.11\.2-3
npm 元数据更新时间：2026-11-11T19:26:02.289Z
中文译文更新时间：2026-11-12T21:41:49.134Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dotcms/create-app
原文对照：https://npmcn.com/package/%40dotcms/create-app/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：90.7 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：7 个
- 首次发布：2026-01-07T00:45:05.506Z
- 最新版本发布：2026-11-11T19:26:02.123Z
- 近 30 天下载量：4803（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：176（近 12 个月 176 个）

## 中文简介

CLI用于脚手架上一个"dotCMS"前端工程或启动本地"dotCMS"多克堆栈.

## 安装

```sh
npm install @dotcms/create-app
```

也可以使用：`pnpm add @dotcms/create-app`、`yarn add @dotcms/create-app`、`bun add @dotcms/create-app`

## README

# @ dotcms/ 创建- app

CLI用于脚手架上一个"dotCMS"前端工程或启动本地"dotCMS"多克堆栈.

## 状态

贝塔 行为和旗帜可能改变.

## 所需资源

-   节点.js 22.22.3+和npm
-   图形
-   多克(用于 `--local` 或者说 `--starter`(中文(简体) )
-   互联网访问( 下载模板; 拖取 Docker 图像)

## 我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 `@dotcms/*` 货包船 地点 **完全相同的版本编号** 作为点CMS的发布,它是为(例如:点CMS)而建的 `26.7.14-1` → `@dotcms/client@26.7.14-1`, (中文(简体) ), `@dotcms/react@26.7.14-1`,等等).

**简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.**

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的东西,所以一个更老的SDK通常会继续工作 对一个新的点CMS案例,罚款。 但偶尔,释放确实包括一个真正的 打破更改——如果您的 SDK 年龄超过此点, 它会停止正确工作 .

你不需要自己去跟踪它: 你的点CMS实例总是知道最古老的SDK 版本它仍然支持,SDK自动对照它检查自己. 狦琌 使用SDK这个太老了,你会看到一个清晰的警告 在你的控制台上告诉你 升级.

**建议:** 将您的 SDK 与您的点CMS 实例相同的版本连接, 并且只接通 当您升级了点CMS, 或者当控制台告诉你.

> **在LTS发布?** LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.
> 
> 想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 [发布和支持生命周期( S)](https://dev.dotcms.com/docs/release-support-lifecycle)。 。 。 .

## 快速启动

```sh
npx @dotcms/create-app my-app
```

全局安装 :

```sh
npm install -g @dotcms/create-app
create-dotcms-app my-app
```

## 国 际

```sh
create-dotcms-app [projectName] [options]
```

| 选项 | 说明 |
| --- | --- |
| `-f, --framework <framework>` | 框架: `nextjs`, (中文(简体) ), `astro`, (中文(简体) ), `angular`, (中文(简体) ), `angular-ssr` |
| `-d, --directory <path>` | 父目录或目标目录 |
| `--local` | 使用带有 Docker 的本地点CMS |
| `--starter <url>` | 自定义启动器 ZIP URL( 只本地; 设置) `CUSTOM_STARTER_URL`(中文(简体) ) |
| `--url <url>` | 云模式的点CMS URL |
| `-u, --username <username>` | 云模式的点CMS 用户名 |
| `-p, --password <password>` | 云模式的点CMS 密码 |
| `-V, --version` | 显示 CLI 版本 |

框架别名 :

-   `next`, (中文(简体) ), `next.js` - > (中文) `nextjs`
-   `ng` - > (中文) `angular`
-   `angular-server` - > (中文) `angular-ssr`

## 模式行为

### 1) 云模式( 已存在的 DotCMS 实例)

未通过时使用 `--local` 或者说 `--starter` 并用提示选择云.

流量 :

1.  校验 URL, 项目名称和旗帜 .
2.  检查点CMS健康状况 `/api/v1/appconfiguration`。 。 。 .
3.  认证( 最多三次尝试) .
4.  读取 `defaultSite` 从 `/api/v1/site/defaultSite`。 。 。 .
5.  配置 UVE 通过 `/api/v1/apps/dotema-config-v2/{siteId}`。 。 。 . **可选** - 如果这失败了 CLI警告,解释如何用手完成,继续.
6.  脚手架选中的前端并运行 `npm install`。 。 。 .
7.  写作 `.env` 使用您的主机、 站点 ID 和 符号( 见 [ `.env`](https://npmcn.com/package/%40dotcms/create-app/#readme-your-env)) (中文(简体) ).

### 2) 本地模式( E)`--local`(中文(简体) )

流量 :

1.  验证 Docker 可用性 .
2.  检查此堆栈公布的端口 : `8082`, (中文(简体) ), `8443` 财务报告和审定财务报表 `8090`。一个已运行的点CMS `8082` 不被视为冲突——见 [如果点CMS已经运行](https://npmcn.com/package/%40dotcms/create-app/#readme-if-dotcms-is-already-running)。 。 。 .
3.  写下 **捆绑** `docker-compose.yml` 输入项目目录(参见 [捆绑的多克堆栈](https://npmcn.com/package/%40dotcms/create-app/#readme-the-bundled-docker-stack)) (中文(简体) ).
4.  运行 `docker compose up -d --wait`,直到每个服务 报告健康,流畅 进步和时间的流逝 长长的第一次拉动 从来不是一个沉默的旋转者.
5.  等待准备 `/dotmgt/readyz`后退为 `/api/v1/appconfiguration`。 。 。 .
6.  以默认本地证书认证( N)`admin@dotcms.com` 编号 : `admin`) (中文(简体) ).
7.  读取 `defaultSite`,配置 UVE(可选的——失败警告并继续),脚手架 前端, 运行 `npm install`。 。 。 .
8.  写作 `.env` 使用您的主机、 站点 ID 和 符号( 见 [ `.env`](https://npmcn.com/package/%40dotcms/create-app/#readme-your-env)) (中文(简体) ).

### 3) 仅启动本地模式( E)`--starter <url>`(中文(简体) )

`--starter` 意味着本地模式.

流量 :

1.  与本地模式相同的 Docker 和端口检查 .
2.  写捆绑 `docker-compose.yml`。 。 。 .
3.  重写 `CUSTOM_STARTER_URL` 内 `docker-compose.yml`。 。 。 .
4.  还有通行证 `CUSTOM_STARTER_URL` 在运行时在编曲环境中.
5.  启动容器,等待健康检查.
6.  跳过前端脚手架和点CMS前端设置流(token,默认站点查找,UVE设置).

当启动器与默认的前端样本流不兼容时使用此功能 .

## 捆绑的多克堆栈

`--local` 财务报告和审定财务报表 `--starter` 写一个 `docker-compose.yml` 那个 **本包裹内的船舶**这是 不再下载 `dotCMS/core` 运行时仓库,所以得到的堆栈是 这个CLI版本是经过测试的,而不是目前使用的 `main`。 。 。 .

堆叠是 `db` (邮政总局), `opensearch`,以及 `dotcms`。 。 。 . `dotcms` 仅在两个之后开始 依赖性报告 **卫生**,并携带 `restart: unless-stopped`因此它不再比赛 启动时后出站.

### 已发布端口

| 端口 | 装订 | 目的 |
| --- | --- | --- |
| `8082` | 所有接口 | 点CMS HTTP |
| `8443` | 所有接口 | 点CMS HTTPS |
| `8090` | **`127.0.0.1` 仅限** | dotCMS 管理端点 |

PostgreSQL 和 OpenSearch 发布 **没有** 端口——只能从构件内部到达 网络,因此在通常的端口上运行您的 Postgres 或 OpenSearch 并不冲突 .

> **为什么8090是循环回放.** 服务于 `/dotmgt/livez`, (中文(简体) ), `/dotmgt/readyz`, (中文(简体) ), `/dotmgt/health` 财务报告和审定财务报表 `/dotmgt/metrics`,并且点CMS授权这些纯粹通过港口的请求到达——有 没有证书检查和IP允许列表 。 约束它 `0.0.0.0` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}会揭发你的情况 健康 和你的网络上的每个人的衡量标准。 肯定会 `127.0.0.1` 故意; 不这样做 "修"为通通.

### 使用不同的作曲文件

设定 `DOTCMS_COMPOSE_URL` 从 URL 获取一个, 而不是使用捆绑的文件 :

```bash
DOTCMS_COMPOSE_URL=https://example.com/my-compose.yml npx @dotcms/create-app my-app --local
```

这是用来救火的逃生舱 文件必须保持一行 `CUSTOM_STARTER_URL:` 条目 或者说 `--starter` 将失败对抗它.

## 如果点CMS已经运行

一个点CMS上 `8082` 先前的运行并非冲突

```
⚠  Found a dotCMS already running at http://localhost:8082
   Docker project "my-app" · Up 8 minutes (healthy)

? How would you like to continue?
❯ Use this instance for my project
  Replace it with a clean instance
  Cancel
```

**替换** 停止 Docker 项目并删除其卷(`docker compose -p <project> down -v`(中文(简体) ) 在开始新鲜。 只有当一个Confose项目拥有港口时才提供这个服务 康普斯不在中央情报局负责破坏.

重复使用需要实例通过准备状态检查 **财务报告和审定财务报表** 发出一个符号; 其它内容 `8082` 仍是一个艰难的失败.

在非交互运行(CI,或无TTY)中,CLI自动重用并打印出通知. 它永远不会取代 没有被问.

##  `.env`

CLI写道: `.env` 以脚手架应用程序读取的值输入您的项目.. `NEXT_PUBLIC_*` 接下来,Js, `PUBLIC_*` 为阿斯特罗. 你不需要手抄任何东西.

现有 `.env` 永远不会被覆盖 : CLI 打印数值, 这样您就可以将它们合并 . 角质没有 `.env` 它读取了 TypeScript `environment` 对象,因此数值被打印为 您要粘贴到环境文件.

## 实例

交互式 :

```sh
npx @dotcms/create-app my-blog
```

地方+具体框架:

```sh
npx @dotcms/create-app my-blog --local --framework nextjs
```

仅启动本地 :

```sh
npx @dotcms/create-app my-blog --starter https://repo.example.com/path/starter.zip
```

有旗相云:

```sh
npx @dotcms/create-app my-blog \
  --framework angular \
  --url https://demo.dotcms.com \
  --username admin@dotcms.com \
  --password admin
```

有堆栈痕迹的调试出错 :

```sh
DEBUG=1 npx @dotcms/create-app my-blog --local
```

## 审定规则

-   URL必须包含协议(`http://` 或者说 `https://`) (中文(简体) ).
-   项目名称被验证为路径 traversal,无效字符,保留了Windows名称,以及长度.
-   如果选择了本地模式( I)`--local` 或者说 `--starter`),云旗被以警告被忽略.
-   现有的非空目标目录需要在清理前确认.

## 解决问题

无法使用 Docker :

-   安装/ 启动 Docker 桌面, 然后重试 .

已经使用的端口 :

-   如果它是以前运行的点CMS,则CLI提出重新使用或替换它——见 [如果点CMS已经运行](https://npmcn.com/package/%40dotcms/create-app/#readme-if-dotcms-is-already-running)。 。 。 .
-   否则,找到主人: `lsof -i :8082` (马克OS/Linux)或 `netstat -ano | findstr ":8082"` (窗户),然后停止它或跑 `docker compose down`。 。 。 .

`zip END header not found` 启动加载时 :

-   启动器 URL 可以到达但不能返回有效的 ZIP 有效有效载荷 .
-   校验文物 URL,仓库权限,以及响应内容类型/机构.

## 开发( 本回购)

构建 :

```sh
pnpm nx build sdk-create-app --skip-nx-cache
```

林特:

```sh
pnpm nx lint sdk-create-app
```

正确验证包装船(装入构成资产到达) `dist/` 和npm 柏油丸:

```sh
pnpm nx verify-package sdk-create-app
```

散点输出 :

-   `dist/libs/sdk/create-app/index.js`
-   ESM 节点CLI在生产建设中与Shebang捆绑
-   可出版软件包包括 JavaScript 文件及 `README.md` 仅(无声明类型)

## 常见问题

### @dotcms/create-app 是什么？

CLI用于脚手架上一个"dotCMS"前端工程或启动本地"dotCMS"多克堆栈\.

### 如何安装 @dotcms/create-app？

在项目目录运行 npm install @dotcms/create-app，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 create-dotcms-app，可以用 npx create-dotcms-app 直接运行。

### @dotcms/create-app 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dotcms\_\_create-app 是否存在。

### @dotcms/create-app 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dotcms/create-app 可以商用吗？

@dotcms/create-app 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcms/create-app 的下载量有多少？

根据 npm 官方下载统计，@dotcms/create-app 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,803 次，日均约 160 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dotcms/create-app 还在维护吗？

最新版本 26\.11\.2-3 发布于 2026/11/12（1 天前）；至今共发布 176 个版本，其中过去 12 个月发布了 176 个；首次发布于 2026/01/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。