> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/fa-bu/adaptive-content/faq-and-troubleshooting.md).

# 常见问题与故障排查

### 我应该为自适应内容使用哪种身份验证方法？

这取决于你想如何控制访问：

* 在一个站点上同时包含公开和私密内容——使用 [签名 Cookie](/docs/documentation/zh/fa-bu/adaptive-content/enabling-adaptive-content/cookies.md)
* 无需身份验证的简单个性化——使用 [URL 参数](/docs/documentation/zh/fa-bu/adaptive-content/enabling-adaptive-content/url.md)
* 一个完全私密的站点——使用 [已认证访问集成](/docs/documentation/zh/fa-bu/adaptive-content/enabling-adaptive-content/authenticated-access.md)
* 已经在使用功能标志——使用 [功能标志提供商](/docs/documentation/zh/fa-bu/adaptive-content/enabling-adaptive-content/feature-flags.md)

### 我可以发布一个部分公开、包含一些需要身份验证内容的站点吗？

可以。你可以保留一个公开站点，其中包含一些需要身份验证的部分，而无需让整个站点都登录：

1. 将你的站点受众设置为公开、未列出或共享链接。
2. 在站点设置中启用自适应内容。
3. 使用 [签名 Cookie](/docs/documentation/zh/fa-bu/adaptive-content/enabling-adaptive-content/cookies.md#signed-cookie) 以便在他们登录到你的主应用后传递访客声明。
4. 为应仅向已认证访客显示的特定页面或部分设置条件。

### 如何使用自定义 OIDC 提供商设置自适应内容？

自适应内容适用于任何身份提供商：

1. 在 GitBook 中设置通用 OIDC 集成。
2. 配置你的 OIDC 提供商，使其在令牌中包含自定义声明。
3. 在你的 GitBook 访客架构中映射这些声明。

常见问题：确保你的提供商在令牌中包含自定义声明（而不只是标准 OIDC 声明），检查声明是否嵌套在提供商特定属性下，并验证令牌格式。不同提供商对自定义声明的结构不同——请查看你提供商的文档。

### 为什么我的分段无法生效或未在预览中显示？

* 确认你的访客架构定义正确。
* 验证你的分段 JSON 是否与架构结构匹配。
* 确保该条件适用于你正在测试的部分、页面或区块。
* 从正确的页面使用预览功能，并在架构更改后刷新预览。

参见 [使用分段进行测试](/docs/documentation/zh/fa-bu/adaptive-content/testing-with-segments.md) 用于完整的测试流程。

### 受限内容会出现在搜索结果中吗？

不会。搜索结果只会反映访客有权访问的内容。位于自适应内容之后的任何部分、页面或区块，仅会被满足查看条件的访客索引并在搜索中可见。

### JWT 声明架构支持自由格式字符串吗？

目前还不支持。声明架构目前仅支持字符串值的枚举，因此请在枚举中定义所有所需的字符串值。

### 自适应内容可以与 JWT 声明中的数组一起使用吗？

不可以。一个声明只提供单个值——字符串（枚举）或布尔值。如果你需要多个值，请在声明提供方一侧进行转换（例如，在 Azure 或 Okta 中）。

### 我该如何调试自适应内容条件？

* 属性名称区分大小写（`role` ≠ `Role`).
* 检查数据类型——布尔值 `true` 不是字符串 `"true"`.
* 检查嵌套条件中的属性路径。
* 在以下位置检查附加到令牌的声明： [jwt.io](https://www.jwt.io/) 以确认你预期的声明正在传递。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/fa-bu/adaptive-content/faq-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.