> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建 Template 模板

`ppio template create` 将 Dockerfile 直接构建成可重用的沙箱模板。它读取 Dockerfile、构建镜像、应用沙箱设置（启动/就绪命令、CPU、内存），并以模板名称注册结果 —— 然后您可以将该名称传递给 `sandbox.create(...)`。

```bash theme={null}
ppio template create <template-name> [options]

# 别名
ppio ct <template-name> [options]
```

## 参数

| 参数                | 必填 | 说明                                                      |
| ----------------- | -- | ------------------------------------------------------- |
| `<template-name>` | 是  | 要创建或重建的模板名称。必须是小写，并且只能包含字母、数字、短横线和下划线（`^[a-z0-9-_]+$`）。 |

## 选项

| 选项                            | 默认值                                | 说明                                                                           |
| ----------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- |
| `-p, --path <path>`           | 当前目录                               | 更改执行命令的根目录。Dockerfile 查找和构建文件上下文相对于它解析。                                      |
| `-d, --dockerfile <file>`     | `ppio.Dockerfile`，然后是 `Dockerfile` | Dockerfile 的路径，相对于根目录。如果没有此选项，CLI 首先查找 `ppio.Dockerfile`，然后回退到 `Dockerfile`。 |
| `-c, --cmd <start-command>`   | —                                  | 沙箱启动时执行的命令。必须与 `--ready-cmd` 一起使用。                                           |
| `--ready-cmd <ready-command>` | —                                  | 必须以退出代码 0 退出才能将模板视为就绪的命令。可以单独使用。                                             |
| `--cpu-count <cpu-count>`     | `2`                                | 用于运行沙箱的 CPU 数量。                                                              |
| `--memory-mb <memory-mb>`     | `512`                              | 用于运行沙箱的内存（单位为兆字节）。必须是偶数。                                                     |
| `--no-cache`                  | 关闭                                 | 构建模板时跳过构建缓存。有关构建缓存的工作原理，请参阅[缓存](/docs/sandbox/template-cache)。                    |
| `--patch-cmd <cmd>`           | —                                  | 在配置阶段结束时修补不兼容的基础镜像的命令。                                                       |

## 行为和验证

* 需要身份验证：使用 `ppio auth login` 登录或在环境中设置 `PPIO_API_KEY`。
* 提供 `--cmd` 而不提供 `--ready-cmd` 将失败并显示 `Both start and ready commands must be provided.`；单独使用 `--ready-cmd` 是允许的。
* 无效的模板名称或奇数的 `--memory-mb` 值会在向服务器发送任何内容之前中止构建。
* 构建日志流式传输到终端。成功后，CLI 打印 Python / JS 代码片段，显示如何从新模板创建沙箱。

## 示例

```bash theme={null}
# 最简：读取当前目录中的 ./ppio.Dockerfile（或 ./Dockerfile）
ppio template create my-python-template

# 显式指定 Dockerfile
ppio template create my-python-template --dockerfile ./Dockerfile

# 完整：自定义根目录、资源、启动/就绪命令、无缓存
ppio template create my-python-template \
  --path ./app \
  --dockerfile ./docker/ppio.Dockerfile \
  --cpu-count 4 \
  --memory-mb 2048 \
  --cmd "python app.py" \
  --ready-cmd "curl -sf http://localhost:8080/health" \
  --no-cache
```

上述命令使用的示例 Dockerfile：

```docker theme={null}
FROM python:3.12

WORKDIR /home/user/app

RUN pip install --no-cache-dir flask requests

COPY app.py .

ENV PORT=8080

CMD ["python", "app.py"]
```

构建完成后，按名称从模板创建沙箱：

```typescript theme={null}
const sandbox = await ppio.sandbox.create('my-python-template')
```