片段

片段把一段 Nginx 配置放在一处统一管理，例如缓存规则、安全响应头或网站的 PHP 处理配置。网站通过 include 引用片段，因此修改片段会同时改变所有引用它的网站。片段位于 网站管理 > 片段。

片段的存放位置

每个片段都是 Nginx 配置目录下 snippets 目录中的一个文件，例如 /etc/nginx/snippets/static-cache.conf。许多发行版本来就把片段放在这里，因此 Nginx 自带的片段（例如 Debian 的 snippets/fastcgi-php.conf）也会列出来。

文件名以 .conf 结尾、且只包含字母、数字、点、连字符和下划线的文件才算片段。snippets/plugins 目录为保留目录，不会被处理。

使用片段

在网站中使用片段有两种方式：

• 引用。 把片段页面显示的指令加到 server 或 location 块中：

  location /assets/ {
      include snippets/static-cache.conf;
  }

  之后片段的每次修改都会作用到这个网站。

• 插入。 在网站编辑器中打开配置模板面板，选择片段并点击 插入。片段的内容会被复制到网站中，之后的修改不会作用到它。同一对话框中的 引用 会替你添加 include 指令。

保存片段时会用 nginx -t 测试整体配置并重载 Nginx。Nginx 拒绝配置时，会保留原来的片段并显示错误。

注意

仍被网站引用的片段无法删除，否则 Nginx 会拒绝配置。片段页面会列出引用它的文件。

编辑片段

编辑页面左侧是片段的内容，右侧是片段的信息；在窄屏上信息显示在内容下方。标题旁的标签说明网站可以引用这个片段，还是只能插入它。在片段页面展开某一行，无需打开编辑器即可查看片段内容。

片段尚未被引用时可以修改文件名。一旦有配置引用它，文件名就不能再修改，以保证该配置继续正常工作。

名称、描述以及变量和选项的显示名称都可以翻译。输入框中是当前界面语言的文字，旁边的翻译按钮用于添加其他语言。没有对应翻译的语言显示英文。

变量

变量让某个值因网站而异，例如目标地址或状态码。每个变量有键名、显示名称、类型（文本、开关或选择）和默认值，内容中以 {{ .键名 }} 引用。

最快的方式是先用真实的值写好配置，然后选中这个值，点击 设为变量，或按 ⌘E（Windows 和 Linux 上为 Ctrl+E）。键名和类型会根据所在行推测，选中的值成为默认值，内容随即改为引用该变量。选中 on 或 off 会创建开关。

在内容中，每个变量都有自己的颜色，与变量列表中的颜色一致，将指针移到变量上会显示它的类型和默认值。输入 {{ . 会列出可补全的变量，列表末尾的 新建变量… 会在光标处声明一个新变量；插入变量 会在光标处插入已有变量。内容中使用但未声明的变量会被标出，并提供声明按钮。

带变量的片段由配置模板面板填写变量，只能插入使用。Nginx 无法直接引用它，因为 {{ }} 占位符不是 Nginx 配置。

预览

内容下方的 预览 左侧是配置模板面板要求使用者填写的表单，右侧是填写后得到的配置。预览随每次修改实时更新：修改任一值，结果随之更新并标出变化的行；预览还会说明结果是否为有效的 Nginx 配置，无需先保存片段。不含变量的片段在同一位置显示引用它的指令。

只包含 {{ if .keepPath }}、{{ else }} 或 {{ end }} 等动作的行不会在结果中留下空行，因此可以把这些动作单独写成一行。

内置模板

片段页面的 内置模板 标签页列出 Nginx UI 自带的配置模板。它们是只读的：展开某一行可以快速查看，打开模板则可以看到变量高亮的原文，并在 预览 中试填变量。复制为片段 会以该模板为基础新建一个片段，修改后即可保存为你自己的片段。

文件头

这些信息保存在文件顶部的文件头中。文件头的每一行都是注释，因此 Nginx 始终可以引用这个文件：

# Nginx UI Template Start
# name = "Redirect"
#
# [description]
# en = "Send every request to another address"
# zh_CN = "将所有请求转发到另一个地址"
#
# [variables.target]
# type = "string"
# name = { en = "Target address" }
# value = "https://example.com"
# Nginx UI Template End

return 301 {{ .target }}$request_uri;

文件头使用配置模板的格式，只是写成了注释，因此也可以手动编辑。只有英文的名称写成普通字符串；带翻译的名称与描述一样，写成按语言划分的表。

同步到节点

片段页面的 同步 会把所有片段复制到你选择的节点并保持更新：保存的片段会复制过去，删除的片段也会从节点上删除。你可以选择是否替换节点上已存在的同名片段。

网站同步到某个节点时，会带上它引用的片段。这些片段只会在节点上缺少时才创建，绝不会替换节点上已有的副本，因为发行版自带的片段在不同节点上可能本来就应该不同。如需替换，请同步片段本身。

提示

片段同步使用的是使用集群节点管理多主机 Nginx 中的目录部署，因此在 配置管理 中，snippets 目录也会显示相同的同步目标。