diff --git a/docs/developer-guide/theme/config.md b/docs/developer-guide/theme/config.md
index eafaa34..5b3d7ff 100644
--- a/docs/developer-guide/theme/config.md
+++ b/docs/developer-guide/theme/config.md
@@ -51,7 +51,7 @@ spec:
 
 | 字段                            | 描述                                                                                          | 是否必填 |
 |---------------------------------|---------------------------------------------------------------------------------------------|---------|
-| `metadata.name`                 | 主题的唯一标识                                                                                | 是       |
+| `metadata.name`                 | 主题的唯一标识，**需要注意：此字段的值需要和主题文件夹名称一致，否则可能导致部分资源无法正常加载。**                                                                                | 是       |
 | `spec.displayName`              | 显示名称                                                                                      | 是       |
 | `spec.author.name`              | 作者名称                                                                                      | 否       |
 | `spec.author.website`           | 作者网站                                                                                      | 否       |
diff --git a/docs/developer-guide/theme/prepare.md b/docs/developer-guide/theme/prepare.md
index aae60ab..fc78997 100644
--- a/docs/developer-guide/theme/prepare.md
+++ b/docs/developer-guide/theme/prepare.md
@@ -32,6 +32,7 @@ Halo 的主题存放于工作目录的 `themes` 目录下，即 `~/halo2-dev/the
 apiVersion: theme.halo.run/v1alpha1
 kind: Theme
 metadata:
+  # 此字段的值需要和主题文件夹名称一致，否则可能导致部分资源无法正常加载。
   name: theme-foo
 spec:
   displayName: 示例主题
@@ -70,6 +71,8 @@ spec:
 
 :::info 提示
 以上 GitHub 都被设置为了模板仓库（Template repository），点击仓库主页的 `Use this template` 按钮即可通过此模板创建一个新的仓库。
+
+创建新的主题仓库并克隆到本地开发环境之后，需要确保主题文件夹名称和 `theme.yaml` 中的 `metadata.name` 字段一致，否则可能导致部分资源无法正常加载。
 :::
 
 ## 创建第一个页面模板
diff --git a/versioned_docs/version-2.15/developer-guide/theme/config.md b/versioned_docs/version-2.15/developer-guide/theme/config.md
index eafaa34..5b3d7ff 100644
--- a/versioned_docs/version-2.15/developer-guide/theme/config.md
+++ b/versioned_docs/version-2.15/developer-guide/theme/config.md
@@ -51,7 +51,7 @@ spec:
 
 | 字段                            | 描述                                                                                          | 是否必填 |
 |---------------------------------|---------------------------------------------------------------------------------------------|---------|
-| `metadata.name`                 | 主题的唯一标识                                                                                | 是       |
+| `metadata.name`                 | 主题的唯一标识，**需要注意：此字段的值需要和主题文件夹名称一致，否则可能导致部分资源无法正常加载。**                                                                                | 是       |
 | `spec.displayName`              | 显示名称                                                                                      | 是       |
 | `spec.author.name`              | 作者名称                                                                                      | 否       |
 | `spec.author.website`           | 作者网站                                                                                      | 否       |
diff --git a/versioned_docs/version-2.15/developer-guide/theme/prepare.md b/versioned_docs/version-2.15/developer-guide/theme/prepare.md
index aae60ab..fc78997 100644
--- a/versioned_docs/version-2.15/developer-guide/theme/prepare.md
+++ b/versioned_docs/version-2.15/developer-guide/theme/prepare.md
@@ -32,6 +32,7 @@ Halo 的主题存放于工作目录的 `themes` 目录下，即 `~/halo2-dev/the
 apiVersion: theme.halo.run/v1alpha1
 kind: Theme
 metadata:
+  # 此字段的值需要和主题文件夹名称一致，否则可能导致部分资源无法正常加载。
   name: theme-foo
 spec:
   displayName: 示例主题
@@ -70,6 +71,8 @@ spec:
 
 :::info 提示
 以上 GitHub 都被设置为了模板仓库（Template repository），点击仓库主页的 `Use this template` 按钮即可通过此模板创建一个新的仓库。
+
+创建新的主题仓库并克隆到本地开发环境之后，需要确保主题文件夹名称和 `theme.yaml` 中的 `metadata.name` 字段一致，否则可能导致部分资源无法正常加载。
 :::
 
 ## 创建第一个页面模板