Python ddgs 模块安装与实战：调用 DuckDuckGo 搜索 API

问题 2：权限错误：Linux/macOS 提示'Permission denied'，可加 --user 选项安装到当前用户目录，或用 sudo 获取权限：

# 方式 1：安装到当前用户目录（推荐，无需管理员权限）
pip install --user ddgs
# 方式 2：用管理员权限安装（谨慎使用）
sudo pip install ddgs

问题 1：网络超时：国内访问 PyPI 官网速度慢，可改用清华镜像源安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ddgs

三、基础使用：3 分钟实现文本、图片、新闻搜索

安装完成后，就能用代码调用搜索功能了。ddgs 模块的核心功能集中在 DDGS() 类中，通过不同方法实现不同类型的搜索，且用法高度统一，容易上手。

1. 文本搜索：获取关键词相关网页

比如想搜索'Python 编程'的前 5 条结果，代码如下，关键步骤已标注注释：

# 1. 导入需要的库：ddgs 用于搜索，time 用于添加延迟（避免请求过于频繁）
from ddgs import DDGS
import time

# 2. 使用 with 语句创建 DDGS 实例（自动管理资源，无需手动关闭）
with DDGS() as ddgs:
    # 3. 调用 text() 方法搜索，max_results 指定返回结果数量
    results = ddgs.text('Python 编程', max_results=5)
    # 4. 遍历结果，打印关键信息（标题、链接、摘要）
    for result in results:
        print(f"标题：{result['title']}")
        print(f"链接：{result['href']}") # href 对应网页链接
        print(f"摘要：{result['body']}") # body 对应网页简介
        print("---") # 分隔不同结果，方便阅读
        time.sleep(1) # 每次请求后延迟 1 秒，避免触发 DuckDuckGo 的请求限制

结果说明：results 是一个生成器，遍历后每个 result 是字典，包含 title（标题）、href（链接）、body（摘要）等键，可根据需求提取对应信息。

2. 图片搜索：获取关键词相关图片 URL

如果需要批量获取'猫咪'相关的图片链接，可调用 images() 方法，代码如下：

from ddgs import DDGS
import time

with DDGS() as ddgs:
    # 调用 images() 方法，max_results=3 表示返回 3 张图片
    results = ddgs.images('猫咪', max_results=3)
    for result in results:
        print(f"图片标题：{result['title']}")
        print(f"图片 URL：{result['image']}") # image 对应图片的直接链接
        print(f"图片来源：{result['source']}") # source 对应图片的原始网站
        print("---")
        time.sleep(1)

实用场景：获取图片 URL 后，可进一步用 requests 库下载图片，实现'关键词→批量下载图片'的自动化流程。

3. 新闻搜索：获取最新行业动态

想跟踪'人工智能'的最新新闻，用 news() 方法即可，代码支持提取新闻标题、链接、发布日期和摘要：

from ddgs import DDGS
import time

with DDGS() as ddgs:
    # 调用 news() 方法，搜索'人工智能'相关新闻
    results = ddgs.news('人工智能', max_results=3)
    for result in results:
        print(f"新闻标题：{result['title']}")
        print(f"新闻链接：{result['url']}") # url 对应新闻网页链接
        print(f"发布日期：{result['date']}") # date 对应新闻发布时间
        print(f"新闻摘要：{result['body']}") # body 对应新闻核心内容
        print("---")
        time.sleep(1)

注意：新闻结果的发布时间可能存在延迟，若需更实时的信息，可结合 time 模块定期执行代码（如每小时运行一次）。

四、高级功能：让搜索结果更精准、更安全

基础搜索能满足简单需求，但在实际项目中，我们常需要自定义搜索规则。ddgs 提供了'区域设置'和'安全搜索'两个核心高级功能，帮你筛选更符合需求的结果。

1. 区域设置：指定搜索结果的地区

比如想获取'Python 的发展趋势'在中国地区的搜索结果（避免出现国外无关内容），可在调用搜索方法时添加 region 参数，常用区域代码如下：

• 中国：zh-cn
• 美国：en-us
• 英国：en-gb

代码示例：

from ddgs import DDGS
import time

with DDGS() as ddgs:
    # 添加 region='zh-cn'，限定搜索结果为中国地区
    results = ddgs.text('Python 的发展趋势', max_results=3, region='zh-cn')
    for result in results:
        print(f"标题：{result['title']}")
        print(f"链接：{result['href']}")
        print("---")
        time.sleep(1)

2. 安全搜索：过滤不适宜内容

如果你的项目面向学生或公众（如教育类工具），需要过滤成人内容或敏感信息，可通过 safesearch 参数设置安全级别，共三个选项：

• off：关闭安全搜索，显示所有结果（不推荐公开场景）；
• moderate：中等安全级别，过滤明显的成人内容（默认值，适合大多数场景）；
• strict：严格模式，过滤更多潜在不适宜内容（适合教育、儿童相关场景）。

代码示例（搜索'Python 编程教程'并启用中等安全级别）：

from ddgs import DDGS
import time

with DDGS() as ddgs:
    # 添加 safesearch='moderate'，确保教程内容无不适宜信息
    results = ddgs.text(
        'Python 编程教程',
        max_results=3,
        region='zh-cn',
        safesearch='moderate'
    )
    print("安全搜索结果：", list(results)) # 转换为列表方便查看
    time.sleep(1)

五、实战案例：批量搜索并保存结果到 JSON 文件

学会了基础和高级功能后，我们来做一个实用项目：输入多个关键词，批量搜索并将结果保存到 JSON 文件，方便后续分析或分享。

项目需求

• 关键词列表：['Python 教程', '机器学习', '数据科学']；
• 功能：对每个关键词进行文本搜索，获取前 3 条结果；
• 输出：将所有结果保存到 search_results.json 文件，支持中文显示。

完整代码（含详细注释）

# 导入需要的库：json 用于保存文件，ddgs 用于搜索，time 用于延迟
import json
from ddgs import DDGS
import time

def search_and_save(keywords, filename='search_results.json'):
    """
    批量搜索关键词并保存结果到 JSON 文件
    参数：
        keywords (list)：要搜索的关键词列表（如 ['Python 教程', '机器学习']）；
        filename (str)：保存结果的文件名，默认是 'search_results.json'。
    返回：
        None（直接保存文件到当前目录）
    """
    # 创建空字典，用于存储所有关键词的搜索结果（键：关键词，值：该关键词的搜索结果）
    all_results = {}
    # 使用 with 语句管理 DDGS 实例
    with DDGS() as ddgs:
        # 遍历每个关键词，逐个搜索
        for keyword in keywords:
            print(f"正在搜索：{keyword}")
            # 对当前关键词进行文本搜索，获取前 3 条结果（转换为列表，避免生成器过期）
            result_list = list(ddgs.text(keyword, max_results=3))
            # 将结果存入字典
            all_results[keyword] = result_list
            time.sleep(1) # 延迟 1 秒，避免请求频繁
    # 保存结果到 JSON 文件
    with open(filename, 'w', encoding='utf-8') as f:
        # ensure_ascii=False：允许中文正常显示（不转义为 Unicode 编码）
        # indent=2：设置缩进为 2 个空格，让 JSON 文件更易读
        json.dump(all_results, f, ensure_ascii=False, indent=2)
    print(f"\n所有搜索结果已保存到：{filename}")

# 测试函数：输入关键词列表，调用函数
if __name__ == "__main__":
    target_keywords = ['Python 教程', '机器学习', '数据科学']
    search_and_save(target_keywords)

运行结果说明

1. 执行代码后，当前目录会生成 search_results.json 文件；
2. 打开文件可看到结构化结果，示例如下（中文正常显示，格式清晰）：

{
  "Python 教程": [
    {
      "title": "Python 入门教程 - 菜鸟教程",
      "href": "https://www.runoob.com/python/python-tutorial.html",
      "body": "Python 是一种解释型、面向对象、动态数据类型的高级程序设计语言..."
    },
    ...
  ],
  "机器学习": [
    {
      "title": "机器学习入门教程 - 斯坦福大学",
      "href": "https://cs229.stanford.edu/",
      "body": "本教程涵盖机器学习的核心概念，包括监督学习、无监督学习、深度学习..."
    },
    ...
  ]
}

六、避坑指南：常见问题与解决方案

在使用 ddgs 模块时，新手可能遇到'请求限制''结果为空'等问题，这里整理了高频问题及解决方法，帮你快速排查。

1. 问题 1：请求限制（DuckDuckGo 阻止频繁请求）

现象：代码运行一段时间后，突然无法获取结果，或报错'Too many requests'。 原因：DuckDuckGo 为保护服务器，对短时间内的请求次数有限制。 解决方案：在每次请求后添加延迟，推荐延迟 1-3 秒（如代码中的 time.sleep(1)），避免短时间内发送大量请求。

2. 问题 2：搜索结果为空

现象：代码无报错，但 results 为空列表，没有任何结果。 原因：可能是关键词太特殊、网络连接异常，或区域设置与关键词不匹配（如用 region='en-us' 搜索中文关键词）。 解决方案：

• 更换更通用的关键词（如将'Python 3.11 新特性教程 2024'改为'Python 3.11 新特性'）；
• 检查网络连接，确保能正常访问 DuckDuckGo 官网；
• 调整 region 参数（如搜索中文关键词时，用 region='zh-cn'）。

3. 问题 3：模块版本过时（功能缺失或报错）

现象：调用某些方法（如 images()）时报错'AttributeError'，提示方法不存在。 原因：使用的 ddgs 版本过旧，旧版本可能不支持新功能。 解决方案：更新 ddgs 到最新版本，执行以下命令：

pip install --upgrade ddgs

七、注意事项：规范使用，避免风险

ddgs 是 DuckDuckGo 的非官方库，使用时需遵守相关规则，避免违规导致功能失效。

1. 遵守 DuckDuckGo 服务条款：不要用 ddgs 进行恶意爬取（如短时间内发送上千次请求），或获取违规内容，否则可能被封禁 IP；
2. 结果差异说明：由于是第三方库，ddgs 返回的结果可能与 DuckDuckGo 官网搜索结果略有不同（如排序顺序、结果数量），如需完全一致的结果，建议直接访问官网；
3. 定期更新库：ddgs 会不断修复 bug 并添加新功能，建议每隔 1-2 个月更新一次（用 pip install --upgrade ddgs），确保使用最新版本；
4. 隐私保护：如果搜索涉及敏感信息，建议在本地环境运行代码，避免将结果上传到公共平台，保护数据安全。

总结

ddgs 模块是 Python 中一款高效的信息检索工具，从安装到实战的核心流程可总结为：'安装模块（推荐虚拟环境）→ 基础搜索（文本 / 图片 / 新闻）→ 高级配置（区域 / 安全级别）→ 实战应用（批量保存结果）→ 避坑排查（请求限制 / 结果为空）'。

无论是批量获取行业资讯、收集图片资源，还是做数据分析前的信息采集，ddgs 都能帮你减少重复操作，提升效率。