跳转到主要内容
重要： 仅在你与平台所有者均已明确授权的系统上使用认证抓取，例如内部、自托管的工具或你完全掌控的资源。除非你确定其符合网站的服务条款，并在存疑时获得书面许可，否则不要在平台上使用身份验证。不当使用会话 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
演示应用：你可以在我们的演示应用中练习：https://firecrawl-auth.vercel.app
  • 邮箱：test@example.com
  • 密码：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 并复制
DevTools Cookies View
对于演示应用，cookie 类似于： 
auth-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJleGFtcGxlLXVzZXItaWQiLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20ifQ.example-signature-hash
重要： 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=== 截图 URL ===\n" + result.screenshot);

​
最佳实践

Cookie 安全

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

Cookie 过期

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

速率限制

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

错误处理

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

​
故障排查

可能原因：
  • Cookie 已过期
  • Cookie 复制不完整或有误
  • 应用需要额外请求头
  • 服务器端会话已失效
解决方案：
  • 重新登录后从 DevTools 重新导出 cookies
  • 检查是否需要多个 cookies（session + CSRF token）
  • 确认 cookie 的域与目标 URL 匹配
针对短时会话：
  • 改用基于表单的身份验证
  • 使用 actions 自动化登录流程
  • 设置定时任务（cron）刷新 cookies
  • 考虑向内部工具管理员申请更长的会话时长
内部工具的 Cookie 有效期： 许多内部工具设置 7–30 天的 cookie 过期时间，适合定期抓取任务。可在 DevTools 中查看 cookie 的 Expires 字段以了解有效期。