Windows10下Docusaurus集成Typesense遇0 hits问题求助

问题现象 #

在Windows 10环境下，为Docusaurus站点配置Typesense搜索引擎，使用Typesense Docker镜像和docsearch scraper时，出现以下问题：

• 运行scraper后始终返回0 hits
• 站点搜索时提示NotFound错误

排查与解决步骤 #

1. 修正Scraper启动命令的路径错误 #

你的Docker启动命令中，挂载配置文件的路径存在空格，导致挂载失败，且CONFIG环境变量指向的路径与挂载路径不一致：

docker run -it --env CONFIG=/app/tsconfig.json --env-file=C:/pathtoenvironmentfile/environment.env -v c:/pathtotypesense config/config.json:/app/config.json typesense/docsearch-scraper 

修正后：

docker run -it --env CONFIG=/app/config.json --env-file=C:/pathtoenvironmentfile/environment.env -v c:/pathtotypesense/config/config.json:/app/config.json typesense/docsearch-scraper 

确保本地配置文件路径无空格，且CONFIG变量指向容器内正确的配置文件路径。

2. 修复Scraper配置文件的语法错误 #

你的config.json中start_urls的URL未闭合双引号，导致配置解析失败：

"start_urls": [
    "http://localhost:3000/pathtomywebsite/
],

修正后：

"start_urls": [
    "http://localhost:3000/pathtomywebsite/"
],

3. 统一索引集合名称 #

Scraper配置中的index_name和Docusaurus配置中的typesenseCollectionName必须完全一致：

• 当前Scraper config："index_name": "Randomname"
• 当前Docusaurus config：typesenseCollectionName: 'Randomstringname'
  修正方案：将两者改为相同名称，比如统一为"Randomname"

4. 调整页面选择器以匹配Docusaurus DOM结构 #

默认Docusaurus v2的内容区域并非使用article标签，而是带有.theme-doc-markdown类的容器，原选择器无法匹配内容导致返回0 hits。修改selectors为：

"selectors": {
    "lvl0": {
        "selector": ".navbar__title",
        "global": true,
        "default_value": "Documentation"
    },
    "lvl1": ".theme-doc-markdown h1",
    "lvl2": ".theme-doc-markdown h2",
    "lvl3": ".theme-doc-markdown h3",
    "lvl4": ".theme-doc-markdown h4",
    "lvl5": ".theme-doc-markdown h5",
    "lvl6": ".theme-doc-markdown h6",
    "text": ".theme-doc-markdown p, .theme-doc-markdown li"
}

可通过浏览器开发者工具确认站点实际DOM结构，调整选择器至正确值。

5. 验证Typesense容器的端口映射 #

确保启动Typesense容器时已将端口8108映射到主机：

docker run -p 8108:8108 typesense/typesense:latest --api-key=myapikey --data-dir=/data

未映射端口会导致scraper和Docusaurus无法连接到Typesense服务。

6. 优化API Key权限（可选） #

当前Docusaurus使用admin key存在安全风险，建议创建search-only密钥：

1. 通过Typesense API生成密钥：

curl -X POST http://localhost:8108/keys \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: myapikey" \
  -d '{
        "description": "Search-only key for Docusaurus",
        "actions": ["documents:search"],
        "collections": ["Randomname"]
      }'

2. 将生成的密钥替换到Docusaurus配置的apiKey字段中。

验证步骤 #

1. 重启Docusaurus站点：npm run start
2. 重新运行修正后的scraper命令，确认返回正常的hits数量
3. 访问站点测试搜索功能，确认不再出现NotFound错误

内容的提问来源于stack exchange，提问作者user11781950