认证抓取

了解如何使用 cookies 抓取需登录访问的内容

重要： 仅在你与平台所有者均已明确授权的系统上使用认证抓取，例如内部、自托管的工具或你完全掌控的资源。除非你确定其符合网站的服务条款，并在存疑时获得书面许可，否则不要在平台上使用身份验证。不当使用会话 cookies 可能违反服务条款或相关法律；务必确认你被授权以此方式访问受保护内容。

​

概览

针对需要身份验证的抓取，推荐使用基于 Cookie 的身份验证，你可以：

1. 手动登录你的应用
2. 从 DevTools 中提取会话 Cookie
3. 使用该 Cookie 配合 Firecrawl 访问受保护页面

Cookie 过期时间：

• 内部工具：通常为 7–30 天或更长
• 其他工具：通常为数小时或数分钟

内部工具的 Cookie 通常有效期更长，因此该方法非常适合周期性抓取任务。

---

​

设置

1. 获取 API Key

   在 firecrawl.dev/app 获取你的 Firecrawl API key

2. 安装依赖

   npm

   npm install @mendable/firecrawl-js
   

   Node.js < v20：如果你使用的是 Node.js 19 或更早版本，还需要安装 dotenv：

   npm install dotenv
   

   并在文件顶部通过 import 'dotenv/config' 引入。

3. 配置环境

   创建一个 .env 文件：

   .env

   FIRECRAWL_API_KEY=your_firecrawl_api_key
   

---

​

方法一：基于 Cookie 的认证

​

步骤 1：从 DevTools 提取 Cookie

演示应用：你可以在我们的演示应用中练习：https://firecrawl-auth.vercel.app

• 邮箱：[e-mail]
• 密码：password123

1. 登录你的应用

   访问 https://firecrawl-auth.vercel.app 并使用上述凭据登录

2. 打开 DevTools

   按下 F12 或右键单击 → “Inspect”

3. 进入 Application 选项卡

   点击 Application 选项卡（Chrome）或 Storage 选项卡（Firefox）

4. 查找并复制 Cookie

   1. 在侧边栏展开 Cookies
   2. 点击你的域名
   3. 找到 auth-token cookie
   4. 双击其 Value 并复制

   

对于演示应用，cookie 类似于：

auth-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJleGFtcGxlLXVzZXItaWQiLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20ifQ.example-signature-hash

重要： Cookie 属于敏感凭证。切勿公开分享或提交到版本控制系统。请像对待密码一样对待它们。

​

第 2 步：在 Firecrawl 中使用 Cookie

import FirecrawlApp from "@mendable/firecrawl-js";

const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

const result = await app.scrape("https://firecrawl-auth.vercel.app/dashboard", {
  formats: ["markdown", "screenshot"],
  headers: {
    Cookie: 'auth-token=COOKIE_GOES_HERE'
  },
  waitFor: 3000, // 等待页面加载额外 3 秒
});

console.log("=== Markdown ===\n" + result.markdown + "\n\n=== Screenshot URL ===\n" + result.screenshot);

​

最佳实践

Cookie 安全

• 将 cookie 存放在环境变量中
• 切勿将 cookie 提交到 Git
• 定期轮换/更新 cookie
• 使用 .gitignore 忽略 .env 文件

Cookie 过期

• 在 DevTools 中检查过期时间
• 在过期前设置告警/提醒
• 过期后重新获取 cookie
• 对于短期有效的 cookie，考虑使用基于表单的认证

速率限制

• 遵守应用的速率限制
• 在请求之间添加延迟
• 监控 429（请求过多）错误
• 重试时使用指数退避

错误处理

• 检查 401/403 错误（cookie 过期）
• 验证响应内容
• 记录认证失败
• 预备备用的认证方式

---

​

故障排查

出现 401 Unauthorized 错误

可能原因：

• Cookie 已过期
• Cookie 复制不完整或有误
• 应用需要额外请求头
• 服务器端会话已失效

解决方案：

• 重新登录后从 DevTools 重新导出 cookies
• 检查是否需要多个 cookies（session + CSRF token）
• 确认 cookie 的域与目标 URL 匹配

Cookie 不生效

请检查：

• Cookie 名称是否正确？
• 是否复制了完整的 cookie 值？
• Cookie 的域是否正确？
• Cookie 是否存在 Path 限制？
• 是否需要多个 cookies？

小技巧： 从 DevTools 复制所有 cookies 并一并测试，然后逐个移除，找出必需的那些。

会话过快过期

针对短时会话：

• 改用基于表单的身份验证
• 使用 actions 自动化登录流程
• 设置定时任务（cron）刷新 cookies
• 考虑向内部工具管理员申请更长的会话时长

内部工具的 Cookie 有效期： 许多内部工具设置 7–30 天的 cookie 过期时间，适合定期抓取任务。可在 DevTools 中查看 cookie 的 Expires 字段以了解有效期。