参考：设置项（SEO_SUITE）¶

所有配置都放在 settings.py 里的一个 SEO_SUITE 字典中。没有写出的键沿用下面列出的包默认值。

# settings.py

SEO_SUITE = {
    # ... only the keys you want to change ...
}

DEFAULTS 和 SITE_DEFAULTS 两个字典会与内置值 深度合并，而不是整体替换——在这两个字典里只需写出想覆盖的键。

完整参考¶

解析¶

键	类型	默认值	说明
`RESOLVER_CLASS`	点分导入路径字符串	`"seo_suite.resolver.Resolver"`	解析器类。替换它可以自定义元数据的收集或合并逻辑。必须是 `seo_suite.resolver.BaseResolver` 的子类。
`SITE_ID_RESOLVER`	点分导入路径字符串或 `None`	`None`	一个 `(request) -> int \\| None` 形式的可调用对象，返回当前站点 ID。为 `None` 时使用标准回退链（sites 框架 → `settings.SITE_ID`）。

全局元数据默认值（优先级最低）¶

键	类型	默认值	说明
`DEFAULTS`	dict	见下文	作为最低优先级层应用到每个页面的部分元数据。与内置默认值深度合并。
`DEFAULTS.title_suffix`	str	`""`	追加到每个页面标题末尾（例如 `" \\| My Site"`）。
`DEFAULTS.robots`	str	`"index,follow"`	默认的 robots 指令。
`DEFAULTS.og`	dict	`{"type": "website"}`	默认的 Open Graph 标签。
`DEFAULTS.twitter`	dict	`{}`	默认的 Twitter 卡片标签。

按站点的默认值¶

键	类型	默认值	说明
`SITE_DEFAULTS`	dict	`{}`	把站点 ID（int）或 `None` 映射到一个部分元数据字典。以优先级 20 应用，高于全局默认值。`None` 键用于兜底，匹配所有未单独配置的站点。

示例：

SEO_SUITE = {
    "SITE_DEFAULTS": {
        1: {"title_suffix": " | Main Site", "og": {"site_name": "Main Site"}},
        2: {"title_suffix": " | Blog", "og": {"site_name": "Blog"}},
    },
}

规范 URL¶

键	类型	默认值	说明
`CANONICAL_DOMAIN`	str 或 `None`	`None`	强制所有规范 URL 使用该域名（例如 `"www.example.com"`）。为 `None` 时使用请求的 `Host` 头。
`FORCE_HTTPS_CANONICAL`	bool	`True`	把所有 `http://` 规范 URL 升级为 `https://`。
`LIST_CANONICAL_INCLUDES_PAGE`	bool	`True`	为 `True` 时，`SeoListViewMixin` 会给第 1 页之后的页面在规范 URL 后追加 `?page=N`；为 `False` 时，所有分页共用同一个规范 URL。

hreflang¶

键	类型	默认值	说明
`HREFLANG_X_DEFAULT`	bool	`True`	`build_hreflang_alternates` 是否添加一条指向 `LANGUAGE_CODE` 对应 URL 的 `x-default` 记录。

缓存¶

键	类型	默认值	说明
`CACHE_TTL`	int	`0`	已解析元数据的缓存 TTL（秒）。`0` 表示禁用缓存。只有基于对象的解析结果（带主键的模型实例）会被缓存。
`CACHE_BACKEND`	str	`"default"`	使用的 Django 缓存别名。
`CACHE_KEY_PREFIX`	str	`"seosuite:v1"`	所有缓存键的前缀。修改它可以一次性让全部缓存条目失效。

可选提供器¶

键	类型	默认值	说明
`OBJECT_MODELS`	str 列表	`[]`	`seoobject` contrib 应用的允许列表。格式：`["app_label.model_name"]`（不区分大小写）。只有列表中的模型才会触发 `SeoObject` 查询。

JSON-LD¶

键	类型	默认值	说明
`DEFAULT_SCHEMA_PROFILES`	str 列表	`[]`	在全局默认层（优先级 10）应用到每个页面的 Schema 配置键。
`JSONLD_SERIALIZER`	点分导入路径字符串	`"seo_suite.schema.default_serializer"`	一个 `(dict) -> str` 形式的可调用对象，把 JSON-LD 字典序列化为字符串。默认实现会转义 `<`、`>` 和 `&` 以防止注入。

后台管理¶

键	类型	默认值	说明
`ADMIN_GROUP_APPS`	bool	`True`	在 Django admin 首页把核心应用和可选 contrib 应用（`seopath` / `seoobject`）合并显示为一个 SEO Suite 分区，而不是各占一个区块。启动时会包装默认 admin 站点的 `get_app_list`，与 admin 的 URL 路径无关。设为 `False` 则每个应用保持独立分区。如果使用自定义的 `AdminSite`，请自行调用 `seo_suite.admin_grouping.install_app_grouping(your_site)`。

robots.txt¶

以下设置控制带版本管理的 robots.txt 工作流。它们不影响 SEO 元数据解析器，也不会改变 <meta name="robots"> 标签。

键	类型	默认值	说明
`ROBOTS_TXT_FALLBACK`	str	`"User-agent: *\nAllow: /"`	当前站点没有激活的数据库版本时，`/robots.txt` 返回的内容。
`ROBOTS_SITEMAP_URLS`	str 列表	`[]`	以 `Sitemap:` 行的形式追加到每次返回的 `robots.txt` 末尾的 URL。相对 URL 会根据当前请求补全为绝对 URL。
`ROBOTS_CACHE_TTL`	int	`0`	渲染后的 `robots.txt` 内容的缓存 TTL（秒）。`0` 表示禁用缓存。任何版本被保存或激活时，缓存都会自动失效。使用与 `CACHE_BACKEND` 相同的后端。

完整示例¶

SEO_SUITE = {
    # ---- resolution ----
    "RESOLVER_CLASS": "seo_suite.resolver.Resolver",
    "SITE_ID_RESOLVER": None,

    # ---- global metadata defaults ----
    "DEFAULTS": {
        "title_suffix": " | My Site",
        "robots": "index,follow",
        "og": {
            "type": "website",
            "site_name": "My Site",
        },
        "twitter": {},
    },

    # ---- per-site defaults ----
    "SITE_DEFAULTS": {},

    # ---- canonical ----
    "CANONICAL_DOMAIN": "www.mysite.com",
    "FORCE_HTTPS_CANONICAL": True,
    "LIST_CANONICAL_INCLUDES_PAGE": True,

    # ---- hreflang ----
    "HREFLANG_X_DEFAULT": True,

    # ---- caching ----
    "CACHE_TTL": 300,
    "CACHE_BACKEND": "default",
    "CACHE_KEY_PREFIX": "seosuite:v1",

    # ---- optional providers ----
    "OBJECT_MODELS": [],

    # ---- JSON-LD ----
    "DEFAULT_SCHEMA_PROFILES": [],
    "JSONLD_SERIALIZER": "seo_suite.schema.default_serializer",

    # ---- admin ----
    "ADMIN_GROUP_APPS": True,

    # ---- robots.txt ----
    "ROBOTS_TXT_FALLBACK": "User-agent: *\nAllow: /",
    "ROBOTS_SITEMAP_URLS": [],
    "ROBOTS_CACHE_TTL": 0,
}