版本：旧版 (v1.x - v2.x)

配置文件

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

DocSearch配置文件示例如下：

{
  "index_name": "example",
  "start_urls": ["https://www.example.com/docs"],
  "selectors": {
    "lvl0": "#content header h1",
    "lvl1": "#content article h1",
    "lvl2": "#content section h3",
    "lvl3": "#content section h4",
    "lvl4": "#content section h5",
    "lvl5": "#content section h6",
    "text": "#content header p,#content section p,#content section ol"
  }
}

`index_name`

这是Algolia索引名称，您的记录将被推送至此。我们提供的apiKey仅限该索引使用，且是仅搜索API密钥。

使用免费版DocSearch爬虫时，indexName始终是配置文件名。若自行运行DocSearch，可任意命名。

{
  "index_name": "example"
}

DocSearch爬虫运行时，会创建临时索引。爬取完成后，将该索引移至index_name指定名称（覆盖现有索引）。

默认临时索引名称为index_name值 + _tmp。

如需自定义名称，请设置INDEX_NAME_TMP环境变量。此变量可在.env文件中配置，与APPLICATION_ID和API_KEY并列。

`start_urls`

此数组包含网站爬取起始URL列表。爬虫将从这些页面递归跟踪所有链接（<a>标签），但不会跟踪跨域链接及匹配stop_urls的链接。

{
  "start_urls": ["https://www.example.com/docs"]
}

`selectors_key`：定制选择器

可根据URL定义更精细的选择器集。需在start_urls中使用selectors_key参数。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/faq/",
      "selectors_key": "faq"
    },
    {
      "url": "http://www.example.com/docs/"
    }
  ],
  […],
  "selectors": {
    "default": {
      "lvl0": ".docs h1",
      "lvl1": ".docs h2",
      "lvl2": ".docs h3",
      "lvl3": ".docs h4",
      "lvl4": ".docs h5",
      "text": ".docs p, .docs li"
    },
    "faq": {
      "lvl0": ".faq h1",
      "lvl1": ".faq h2",
      "lvl2": ".faq h3",
      "lvl3": ".faq h4",
      "lvl4": ".faq h5",
      "text": ".faq p, .faq li"
    }
  }
}

爬虫遍历start_urls项匹配URL，仅应用首个匹配项的选择器子集。

假设URL为http://www.example.com/en/api/，配置如下：

{
  "start_urls": [
    {
      "url": "http://www.example.com/doc/",
      "selectors_key": "doc"
    },
    {
      "url": "http://www.example.com/doc/faq/",
      "selectors_key": "faq"
    },
   […],
  ]
}

仅与doc相关的选择器集将应用于该URL。正确配置方式应反向构建（如先前所述）。

若start_urls项未定义selectors_key，则使用default选择器集。请务必设置此回退选择器集。

使用正则表达式

start_urls和stop_urls支持正则表达式实现复杂匹配模式。可定义为正则表达式数组或对象，对象必须包含指向可访问页面的url键。

若以对象形式定义正则表达式，可添加variables键注入特定URL模式变量。下例阐明此特性：

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
      "variables": {
        "lang": ["en", "fr"],
        "version": ["latest", "3.3", "3.2"]
      }
    }
  ]
}

此语法的附加效果是：从http://www.example.com/docs/en/latest匹配页面提取的所有记录将包含属性lang: en和version: latest，便于通过这些facetFilters筛选。

下例展示UI如何筛选特定语言和版本的结果。

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["lang:en", "version:latest"]
  },
  […],
});

使用自定义标签

无需正则表达式即可为特定页面添加自定义标签。在tags键中添加标签列表，这些标签将自动成为Algolia中的分面，支持按值筛选。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/concepts/",
      "tags": ["concepts", "terminology"]
    }
  ]
}

JS代码片段示例：

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["tags:concepts"]
  },
});

使用页面权重

用于提升特定页面优先级。此参数可增强页面生成的记录权重，高page_rank页面结果将优先于低page_rank页面。注意可传递任意数值（包括负值）。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/concepts/",
      "page_rank": 5
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "page_rank": 1
    }
  ]
}

本例中，《概念》页面生成的记录将优先于《贡献者》页面结果。

按页面使用自定义选择器

如果您的网站标记在不同页面间差异巨大，无法使用通用选择器，可以通过命名空间方式组织选择器，并为特定页面指定应使用的选择器集合。

{
  "start_urls": [
    "http://www.example.com/docs/",
    {
      "url": "http://www.example.com/docs/concepts/",
      "selectors_key": "concepts"
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "selectors_key": "contributors"
    }
  ],
  "selectors": {
    "default": {
      "lvl0": ".main h1",
      "lvl1": ".main h2",
      "lvl2": ".main h3",
      "lvl3": ".main h4",
      "lvl4": ".main h5",
      "text": ".main p"
    },
    "concepts": {
      "lvl0": ".header h2",
      "lvl1": ".main h1.title",
      "lvl2": ".main h2.title",
      "lvl3": ".main h3.title",
      "lvl4": ".main h5.title",
      "text": ".main p"
    },
    "contributors": {
      "lvl0": ".main h1",
      "lvl1": ".contributors .name",
      "lvl2": ".contributors .title",
      "text": ".contributors .description"
    }
  }
}

在此示例中，所有文档页面将使用selectors.default定义的选择器，而./concepts路径下的页面将使用selectors.concepts，./contributors路径下的页面则使用selectors.contributors。

`selectors`

此对象包含用于创建记录层级的所有CSS选择器，最多支持6个层级（lvl0、lvl1、lvl2、lvl3、lvl4、lvl5）以及text字段。

典型配置是将页面title或h1设为lvl0，h2设为lvl1，h3设为lvl2，p设为text，但这高度取决于具体标记结构。

text字段为必填项，但强烈建议同时设置lvl0、lvl1和lvl2以建立有效的相关性深度。

{
  "selectors": {
    "lvl0": "#content header h1",
    "lvl1": "#content article h1",
    "lvl2": "#content section h3",
    "lvl3": "#content section h4",
    "lvl4": "#content section h5",
    "lvl5": "#content section h6",
    "text": "#content header p,#content section p,#content section ol"
  }
}

选择器可直接以字符串形式提供，也可作为包含selector键的对象。其他特殊键的设置方式如下文所述。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1"
    }
  }
}

使用全局选择器

默认的内容提取方式是按HTML标记自上而下读取。这种方式适用于半结构化内容（如标题层级），但当关键信息不在同一文档流中时（例如标题不在页眉或侧边栏内）将失效。

此时可将选择器设为全局（global），使其匹配整个页面，且该页提取的所有记录共享相同值。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "global": true
    }
  }
}

不建议将text选择器设为全局。

设置默认值

当选择器未在页面上匹配到有效元素时，可通过default_value设置回退值。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "default_value": "Documentation"
    }
  }
}

移除多余字符

某些文档会在标题中添加特殊字符（如#或›），这些字符仅有样式意义却不含语义，不应被索引到搜索结果中。

可通过strip_chars键定义需要从最终索引值中排除的字符列表。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "strip_chars": "#›"
    }
  }
}

注意：也可在配置根节点直接设置strip_chars，此时该设置将应用于所有选择器。

{
  "strip_chars": "#›"
}

使用XPath替代CSS定位元素

CSS选择器简洁明了，但存在局限性（如无法在DOM树中向上追溯）。

如果你需要更强大的选择器机制，可以通过设置 type: xpath 来使用 XPath 编写选择器。

下面的例子将寻找一个 li.chapter.active.done，然后在 DOM 中向上遍历两级，直到找到一个 a。这个 a 的内容随后将被用作 lvl0 选择器的值。

{
  "selectors": {
    "lvl0": {
      "selector": "//li[@class=\"chapter active done\"]/../../a",
      "type": "xpath",
      "global": true
    }
  }
}

XPath 选择器可能难以阅读。我们强烈建议您先在浏览器中测试它们，确保匹配结果符合预期。

`custom_settings` 可选

此键可用于覆盖Algolia索引设置。不建议修改默认设置，因其已针对各类网站优化。

`custom_settings.separatorsToIndex`可选

典型用例是配置separatorsToIndex设置。默认Algolia会将所有特殊字符视为单词分隔符，但在方法名等场景中，可能需要保留_、/或#的语义。

{
  "custom_settings": {
    "separatorsToIndex": "_/"
  }
}

更多Algolia设置信息请参阅官方文档。

`custom_settings.synonyms` 可选

custom_settings 可包含 synonyms 键，其值为同义词数组。每个元素是单字同义词组成的数组，这些单词可互换使用。

例如：

"custom_settings": {
    "synonyms": [
      [
        "js",
        "javascript"
      ],
      [
        "es6",
        "ECMAScript6",
        "ECMAScript2015"
      ]
    ]
  },

请注意，您可以使用 Algolia 的高级同义词功能。我们的爬虫仅支持常规的单字同义词。

`scrape_start_urls` 可选

默认情况下，爬虫会从 start_urls 定义的页面提取内容。若您的 starts_urls 页面无有价值内容或与其他页面重复，应将其设为 false。

{
  "scrape_start_urls": false
}

`selectors_exclude` 可选

该参数接收 CSS 选择器数组。在提取页面数据前，匹配这些选择器的元素将被移除。

此功能可用于移除目录、侧边栏或页脚等元素，简化其他选择器的编写。

{
  "selectors_exclude": [".footer", "ul.deprecated"]
}

`stop_urls` 可选

此参数为字符串或正则表达式数组。当爬虫即将访问链接时，会检查其是否匹配数组内容，匹配则跳过访问。用于限制爬虫应访问的页面范围。

注意：此功能常通过添加 http://www.example.com/docs/index.html 来避免重复内容（当 http://www.example.com/docs/ 已是 start_urls 时）。

{
  "stop_urls": ["https://www.example.com/docs/index.html", "license.html"]
}

`min_indexed_level` 可选

默认值为 0。增大该值可不索引 lvlX 匹配不足的记录。例如设为 min_indexed_level: 2 时，爬虫仅索引至少设置了 lvl0、lvl1 和 lvl2 的临时记录。更多策略详见此章节。

当文档存在共享相同 lvl0 和 lvl1 的页面时，此功能尤其有用。此时您可能希望避免索引所有共享记录，而保留页面间的内容差异。

{
  "min_indexed_level": 2
}

`only_content_level` 可选

当 only_content_level 设为 true 时，爬虫不会为 lvlX 选择器创建记录。

启用此参数时，min_indexed_level 将被忽略。

{
  "only_content_level": true
}

`nb_hits` 特殊参数

此数值表示 DocSearch 提取并索引的记录数。我们内部监控此参数以识别意外波动（可能预示配置错误）。

每次运行 DocSearch 时，nb_hits 会自动更新。若在终端环境运行，更新前会请求确认。要跳过确认，请在 .env 文件中设置环境变量 UPDATE_NB_HITS 为 true（启用）或 false（禁用），该文件与 APPLICATION_ID 和 API_KEY 位于同一目录。

您无需手动编辑此字段。此处说明仅为解释其用途。

站点地图

若网站包含 sitemap.xml 文件，可通知 DocSearch 使用其定义待爬取页面。

`sitemap_urls` 可选

可传递指向站点地图文件的 URL 数组。设置此值后，DocSearch 将从站点地图读取 URL，而非追踪 starts_urls 的每个链接。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
}

必须显式定义此参数，我们的爬虫不遵循 robots.txt。

`sitemap_alternate_links` 可选

Sitemaps 可能包含 URL 的_替代链接_。这些链接指向同一页面的其他版本，可能是不同语言或不同 URL 的页面。默认情况下，DocSearch 会忽略这些 URL。

若需要同时抓取这些其他版本，请将此选项设为 true。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
  "sitemap_alternate_links": true
}

使用上述配置配合下方 sitemap.xml 文件时，http://www.example.com/docs/ 和 http://www.example.com/docs/de/ 都将被爬取。

  <url>
    <loc>http://www.example.com/docs/</loc>
    <xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
  </url>

JavaScript 渲染

默认情况下，DocSearch 要求网站采用服务器端渲染，即 HTML 源码由服务器直接返回。若您的内容由前端生成，则需告知 DocSearch 通过 Selenium 模拟浏览器环境。

由于客户端爬取速度远低于服务器端爬取，我们强烈建议您升级网站以启用服务器端渲染。

`js_render` 可选

如果网站需要客户端渲染，请将此值设为 true。这将使 DocSearch 启动 Selenium 代理来获取所有网页内容。

{
  "js_render": true
}

`js_wait` 可选

若网站加载缓慢，可使用 js_wait 指定页面内容提取前的等待时间（单位：秒）。

请注意：此选项会显著增加爬取时间，建议优先考虑启用服务器端渲染方案。

当 js_render 设为 false 时，此选项无效。

{
  "js_render": true,
  "js_wait": 2
}

`use_anchors` 可选

采用客户端渲染的网站常使用 URL 哈希值（# 后的部分）替代完整 URL。

若网站采用此类 URL 结构，请将 use_anchors 设为 true 以确保 DocSearch 索引所有内容。

{
  "js_render": true,
  "use_anchors": true
}

`user_agent` 可选

可覆盖用于网站爬取的用户代理。默认值为：

Algolia DocSearch Crawler

当需要浏览器模拟爬取时（即 js_render=true），我们的 user_agent 是：

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/71.0.3578.98 Safari/537.36

在配置中覆盖用户代理：

{
  "user_agent": "Custom Bot"
}

index_name​

start_urls​

selectors_key：定制选择器​

使用正则表达式​

使用自定义标签​

使用页面权重​

按页面使用自定义选择器​

selectors​

使用全局选择器​

设置默认值​

移除多余字符​

使用XPath替代CSS定位元素​

custom_settings 可选​

custom_settings.separatorsToIndex可选​

custom_settings.synonyms 可选​

scrape_start_urls 可选​

selectors_exclude 可选​

stop_urls 可选​

min_indexed_level 可选​

only_content_level 可选​

nb_hits 特殊参数​

站点地图​

sitemap_urls 可选​

sitemap_alternate_links 可选​

JavaScript 渲染​

js_render 可选​

js_wait 可选​

use_anchors 可选​

user_agent 可选​