# 模板名称
<subtitle>理解和管理模板名称</subtitle>

模板名称是用于引用和从模板创建沙箱的唯一标识符。它们作为人类可读的名称，使您可以轻松识别和在应用程序中使用模板。

## 什么是模板名称？

名称是您在构建模板时分配给模板的字符串标识符。一旦使用名称构建了模板，您就可以使用该名称从模板创建沙箱。

```python
# 使用名称构建模板
Template.build(
    template,
    'my-python-env',
    cpu_count=2,
    memory_mb=2048,
)

# 使用名称创建沙箱
sandbox = Sandbox.create('my-python-env')
```

## 名称格式

在使用名称之前，会修剪其周围的空格并转换为小写。结果必须匹配模式 `^[a-z0-9-_]+$`：

- 小写字母（`a`–`z`）、数字（`0`–`9`）、短横线（`-`）和下划线（`_`）
- 长度在 1 到 128 个字符之间
- 允许前导和尾随短横线或下划线

大写字母在输入时被接受并自动转换为小写，因此 `My-Template` 和 `my-template` 指的是同一个名称。任何其他字符（名称内的空格、点、斜杠等）都会被拒绝。

## 项目范围命名

模板名称限定在您的项目内。这意味着：

- 您名为 `my-app` 的模板存储为 `<项目ID>/my-app`，例如 `6173323/my-app`
- 您可以在同一项目内简单地将其引用为 `my-app`
- 不同项目可以拥有自己的 `my-app` 模板而不会冲突
- 跨项目引用模板时需要使用完整的命名空间格式（`<项目ID>/template-name`）

> 项目 ID 可以在 UCloud 控制台的项目设置中查看。

## 常见用例

### 开发和生产环境

为不同环境使用不同的名称：

```python
# 开发模板
Template.build(
    template,
    'myapp-dev',
    cpu_count=1,
    memory_mb=1024,
)

# 生产模板
Template.build(
    template,
    'myapp-prod',
    cpu_count=4,
    memory_mb=4096,
)
```

### 多个模板变体

创建具有不同配置的同一模板的不同变体：

```python
# 小型实例
Template.build(
    template,
    'myapp-small',
    cpu_count=1,
    memory_mb=512,
)

# 大型实例
Template.build(
    template,
    'myapp-large',
    cpu_count=8,
    memory_mb=8192,
)
```

> 当使用相同的模板定义但不同的 CPU/RAM 配置构建变体时，UCloud Sandbox 的缓存系统将重用通用层，使后续构建更快。

## 检查名称可用性

您可以使用 `exists` 方法检查团队内是否已使用某个名称。

```python
from ucloud_sandbox import Template

exists = Template.exists('my-template')
print(f"名称 {'已被占用' if exists else '可用'}")
```

## 最佳实践

1. **使用描述性名称**：选择清楚表明模板用途或配置的名称
2. **使用标签进行版本控制**：不要在名称中包含版本号，而是使用 [标签](/docs/agent-sandbox/template/tags.md) 进行版本管理（例如，`myapp:v1`、`myapp:v2`）
3. **使用一致的命名**：为您的团队建立命名约定并坚持使用