错误报告

相关源文件

• .github/ISSUE_TEMPLATE/bug-report.yml

目的与范围

本文档提供了为 Sherlock 项目提交有效错误报告的指南。妥善记录的错误报告有助于维护人员高效地理解、重现和修复问题。本指南解释了如何报告错误、应包含哪些信息以及确保您的错误报告可操作的最佳实践。

有关项目一般贡献的信息，请参阅贡献指南。有关可能有助于将您的错误报告定向给正确人员的所有权信息，请参阅代码所有权。

什么是错误

Sherlock 中的错误是指在使用软件时，与所记录的功能不符的任何意外行为、错误或故障。这可能包括

• 执行期间的崩溃或异常
• 不正确的用户名搜索结果
• 意外的假阳性或假阴性
• 性能问题或资源消耗问题
• 连接到支持站点的失败
• 安装问题

错误与功能请求决策树

来源：.github/ISSUE_TEMPLATE/bug-report.yml32-46

Bug 报告流程

在哪里报告错误

所有 Sherlock 的错误报告都应作为 GitHub 仓库上的议题提交。该项目使用标准化的议题模板，以确保收集所有必要信息。

错误报告流程

来源：.github/ISSUE_TEMPLATE/bug-report.yml1-72

报告前准备

在提交错误报告之前，请执行以下准备步骤

1. 检查现有议题: 搜索 GitHub 议题，查看您的错误是否已被报告
2. 更新到最新版本: 运行 pip install --upgrade sherlock-project 或通过您的安装方法更新
3. 验证安装: 确保 Sherlock 已正确安装
4. 检查您的 Python 版本: 确认您正在使用受支持的 Python 版本
5. 尝试基本故障排除: 重启 Sherlock，检查您的网络连接，并尝试使用一个已知可用的用户名

首先检查常见问题

问题类型	可能原因	故障排除步骤
假阴性	限流	稍候再试或使用 VPN
连接错误	网络限制	检查防火墙设置或尝试其他网络
站点错误	最近的站点更改	检查站点是否更改了其布局或 API
未找到用户名	格式限制	验证用户名是否符合站点要求
安装错误	环境问题	检查 Python 版本和依赖项

来源：.github/ISSUE_TEMPLATE/bug-report.yml32-46

创建有效的错误报告

Sherlock 使用标准化的错误报告模板。以下是如何有效地填写每个部分

安装方法字段

从下拉菜单中选择您用于安装 Sherlock 的方法

• PyPI（通过 pip）
• Homebrew
• Docker
• Kali 仓库（通过 apt）
• 从源代码构建
• 其他

此字段很重要，因为错误可能特定于某些安装方法，并且某些软件包由社区而非 Sherlock 项目团队维护。

来源：.github/ISSUE_TEMPLATE/bug-report.yml5-21

软件包版本字段

通过运行以下命令报告您正在使用的 Sherlock 的确切版本

sherlock --version

在指定字段中包含完整的版本号。这有助于维护人员确定该错误是否已在新版本中修复。

来源：.github/ISSUE_TEMPLATE/bug-report.yml22-30

描述字段

一个好的描述应清楚地解释

• 您当时正在尝试做什么
• 您期望发生什么
• 实际发生了什么

遵循建议的格式

When doing {action}, the expected result should be {expected result}.
When doing {action}, however, the actual result was {actual result}.
This is undesirable because {reason}.

来源：.github/ISSUE_TEMPLATE/bug-report.yml31-46

重现步骤字段

列出重现该错误所需的精确步骤，包括

1. 使用的命令行参数
2. 正在搜索的用户名
3. 任何特定的配置设置
4. 任何可能相关的环境因素

示例

1. Install Sherlock via pip: `pip install sherlock-project`
2. Run the command: `sherlock username123 --timeout 10`
3. Observe the error when checking site X

来源：.github/ISSUE_TEMPLATE/bug-report.yml47-56

附加信息字段

包括任何其他相关详细信息，例如

• 操作系统和版本
• Python 版本
• 网络环境（家庭网络、VPN、企业网络）
• 屏幕截图或错误日志
• 您发现的任何解决方法

来源：.github/ISSUE_TEMPLATE/bug-report.yml57-63

行为准则协议

在提交之前，您必须勾选提供的方框，表示同意遵守项目的行为准则。

来源：.github/ISSUE_TEMPLATE/bug-report.yml64-71

一个好的错误报告的构成

来源：.github/ISSUE_TEMPLATE/bug-report.yml1-72

错误报告示例

有效错误报告示例

Installation method: PyPI (via pip)
Package version: 0.14.2

Description:
When searching for a username that contains special characters like "user@name", the expected result should be proper URL encoding of the special characters in the requests. However, the actual result was HTTP 400 errors for sites that don't handle unencoded special characters. This is undesirable because it produces false negatives in the search results.

Steps to reproduce:
1. Install Sherlock via pip: `pip install sherlock-project`
2. Run the command: `sherlock user@name`
3. Observe the error logs for sites returning HTTP 400

Additional information:
- OS: Ubuntu 20.04
- Python: 3.8.10
- The error occurs consistently for sites X, Y, and Z
- The following error appears in the output: [error log details]

无效错误报告示例

Installation method: Select one
Package version: latest

Description:
Sherlock doesn't work properly.

Steps to reproduce:
I tried to search for a username and it didn't work right.

Additional information:
Please fix this.

提交错误报告后

1. 保持响应: 维护人员可能需要额外信息来诊断问题。请留意您议题上的评论并及时回复。
2. 保持耐心: Sherlock 项目由志愿者在业余时间维护。
3. 积极协作: 如果您能在调查进展时测试潜在的修复方案或提供更多信息，将有助于更快地解决问题。
4. 问题解决后请更新: 如果您自行解决了问题，请在错误报告中更新您的解决方案。

错误报告处理流程

来源：.github/ISSUE_TEMPLATE/bug-report.yml1-72

常见问题和故障排除

在报告错误之前，请考虑以下常见问题

速率限制

许多社交媒体网站限制单个 IP 地址的请求数量。这可能导致 Sherlock 错误地报告用户名不存在。请稍候再试或使用不同的网络连接。

网络限制

防火墙、VPN 或网络策略可能会阻止对某些站点的请求。尝试从不同的网络运行 Sherlock，以确认这是否是问题所在。

站点变更

网站经常更新其布局和 API，这可能会暂时破坏 Sherlock 的检测方法。检查问题是否仅限于某个特定站点，因为这可能表明该站点已更改其结构。

无效的用户名格式

某些站点有特定的用户名要求。如果用户名违反了这些要求，您可能会遇到看似错误的假阴性结果，但实际上是预期行为。

来源：.github/ISSUE_TEMPLATE/bug-report.yml32-46