将任意网站转化为 LLM 可用数据的展示型全栈应用。 项目概述Firecrawl 示例页面是一个基于Next.js 16的全栈 Web 应用它复现了 Firecrawl 的核心价值主张将任意网页抓取为干净的 Markdown直接供大语言模型LLM消费。应用本身是一个“展示型 功能型”页面 —— 既有营销落地页的视觉冲击火焰主题、动画、渐变又有可实际操作的在线抓取演示Live Demo。用户输入任意 URL即可获得清洗后的 Markdown、统计数据和原始 HTML。维度选型前端框架Next.js 16App Router React 19样式方案Tailwind CSS 4 shadcn/uinew-york 风格动画库Framer Motion后端运行时Node.jsNext.js Route Handler数据抓取z-ai-web-dev-sdkpage_reader函数数据库Prisma ORM SQLite构建工具Bun反向代理Caddy部署模式Standalone 产物 进程编排 系统架构应用采用经典的“单页前端 API 后端 进程编排”三层结构。前端通过 HTTP 调用后端 API后端借助z-aiSDK 获取目标网页并转换为 Markdown部署层由 Caddy 统一入口将请求分发到 Next.js 服务和可选的 mini-services。HTTP / fetch带 ?XTransformPortN 的请求其余请求/api/scrape调用无头浏览器抓取htmlToMarkdownPrisma浏览器用户Caddy 反向代理 :81Mini-Services 子服务 :NNext.js Standalone :3000Route Handlerz-ai-web-dev-sdkpage_reader目标网页 HTML清洗后 MarkdownSQLite请求流转以 Live Demo 为例当用户在LiveDemo中输入 URL 并点击Scrape时数据流经以下路径前端发起POST /api/scrape请求体{ url: string }。Caddy将请求转发到 Next.js 的3000端口。Route Handler校验 URL 合法性调用ZAI.create()初始化 SDK。SDK 的page_reader函数无头抓取目标页面返回标题、HTML、发布时间等元数据。htmlToMarkdown()将原始 HTML 清洗并转换为Markdown。后端组装响应markdown、stats、fetchedAt返回 JSON。前端在Markdown / Stats / Raw三个标签页中展示结果。⚙️ 核心原理解析 网页抓取链路抓取链路的灵魂是z-ai-web-dev-sdk提供的page_reader函数。它封装了无头浏览器渲染 内容提取的完整流程constzaiawaitZAI.create();constresultawaitzai.functions.invoke(page_reader,{url});page_reader的工作分为三个阶段页面渲染—— 启动无头 Chrome导航到目标 URL等待页面加载完成。这保证了 JavaScript 渲染的 SPA、动态加载内容都能被正确捕获。内容提取—— 从渲染后的 DOM 中提取标题、最终 URL经重定向、完整 HTML 和发布时间检查多种 meta 标签。用量统计—— 返回usage.tokens记录本次抓取消耗的 token 数用于计费和监控。拿到原始 HTML 后后端调用自定义的htmlToMarkdown()进行清洗和格式转换 —— 这是整个应用的“价值放大器”。 HTML 转 Markdown 算法htmlToMarkdown()位于src/lib/html-to-markdown.ts用纯正则 递归下降实现了一个轻量级转换器不依赖第三方库约 150 行代码。处理管线原始 HTML剥离噪声标签script/style/nav/footer/注释提取 main/article聚焦主内容区块级元素转换标题/代码块/引用/列表/表格行内元素转换链接/图片/加粗/斜体/代码清理残余标签 压缩空行干净 Markdown关键设计亮点噪声剥离优先移除script、style、nav、footer、header、svg等非内容标签避免污染统计和 token 消耗。递归下降对div、section、article等容器递归处理能应对任意深度的嵌套。行内与块级分离inlineToMarkdown()专注处理链接、图片、加粗、斜体、代码等在块级转换中被反复调用职责单一。HTML 实体解码支持nbsp;、amp;、#39;等命名、数字和十六进制实体确保输出无转义残留。表格支持能将简单 HTML 表格转换为 Markdown 管道表格格式。取舍说明正则方案比 DOM 解析更快且零依赖但无法处理畸形 HTML。对于结构良好的网页博客、文档站、新闻页输出质量足以支撑 LLM 消费。 部署架构原理 Standalone 构建模式next.config.ts中声明output: standalone这是 Next.js 的生产部署优化模式。构建时会将所有必需的node_modules依赖追踪并打包进.next/standalone/目录产出一个自包含的server.js可直接用bun server.js或node server.js运行无需在部署环境安装依赖。构建脚本build.sh包含“自愈”机制如果构建后server.js不存在例如误删配置会自动注入配置并重新构建。完整构建收集流程bun installbun run buildnext build生成 .next/standalone/server.js生成 .next/static/复制 public/复制到 next-service-dist/database-runtime-build.sh初始化数据库python-runtime-build.sh固化 Python 依赖mini-services-build.sh编译子服务tar -czf 打包 Caddy 反向代理Caddyfile配置了基于查询参数的智能路由:81 { transform_port_query { query XTransformPort* } handle transform_port_query { reverse_proxy localhost:{query.XTransformPort} } handle { reverse_proxy localhost:3000 } }这个设计使得所有子服务mini-services都可通过同一个81端口访问 —— 前端只需在 URL 中附加?XTransformPort3003Caddy 自动将请求路由到对应端口解决了端口暴露和跨域问题。️ 数据库运行时处理database-runtime-build.sh在构建阶段处理数据库若 Preview 环境已有db/custom.db则复制否则初始化空数据库并对构建产物中的数据库执行prisma db push同步 schema。start.sh运行时检查数据库文件是否存在默认路径/app/db/custom.db若缺失则直接终止启动避免连接到空数据库。也可通过DATABASE_URL环境变量指定外部数据库。 Python 运行时支持python-runtime-build.sh处理可选的 Python 依赖检测项目中是否存在.py源文件、requirements.txt或pyproject.toml。用uv将生产依赖安装到构建产物的python-runtime/site-packages/。修复 console scripts 的 shebang使运行时能正确解析。复制源码到部署产物保持相对路径。start.sh运行时检测到该目录后会将其加入PYTHONPATH和PATH使 Next.js 及其子进程能直接使用打包的 Python 环境。 Firecrawl API 使用指南Firecrawl 提供了一整套将网页转化为 LLM 就绪数据的 API包括搜索、抓取、交互等核心能力。以下为快速上手示例。 无密钥快速开始无需 API Key 即可体验基础功能有速率限制。需要更高限制时可在 Firecrawl App 获取 Key 并添加请求头Authorization: Bearer $FIRECRAWL_API_KEY。 1. 搜索Search搜索网络并返回结果页面的完整内容。# cURLcurl-s-XPOSThttps://api.firecrawl.dev/v2/search\-HContent-Type: application/json\-d{query: firecrawl, limit: 3}# Python SDKfromfirecrawlimportFirecrawl firecrawlFirecrawl()# 无需 API Keyresultsfirecrawl.search(firecrawl,limit3)print(results)// Node.js SDKimport{Firecrawl}fromfirecrawl;constfirecrawlnewFirecrawl();constresultsawaitfirecrawl.search(firecrawl,{limit:3});console.log(results); 2. 抓取Scrape抓取任意 URL获得 Markdown、HTML 或结构化 JSON。curl-s-XPOSThttps://api.firecrawl.dev/v2/scrape\-HContent-Type: application/json\-d{url: https://firecrawl.dev, formats: [markdown, html]}返回示例节选{success:true,data:{markdown:# Home - Firecrawl\n\n...,html:!DOCTYPE html...,metadata:{title:Home - Firecrawl,description:...}}}️ 3. 交互Interact抓取页面后可以继续与之交互点击按钮、填写表单、提取动态内容等。# 1. 抓取 Amazon 首页resultapp.scrape(https://www.amazon.com,formats[markdown])scrape_idresult.metadata.scrape_id# 2. 搜索产品并获取价格app.interact(scrape_id,promptSearch for iPhone 16 Pro Max)responseapp.interact(scrape_id,promptClick on the first result and tell me the price)print(response.output)# 3. 停止会话app.stop_interaction(scrape_id) 更多能力功能说明Map发现网站上的所有 URLCrawl递归抓取整个网站Parse将本地 PDF、DOCX、XLSX、HTML 等转换为 Markdown 或 JSONBrowser Sandbox托管浏览器会话适用于交互式工作流Webhooks异步事件通知️ 安装与部署示例项目环境要求依赖版本要求用途Bun 1.0包管理 构建 运行时Node.js 20Next.js 运行时基础Caddy 2生产环境反向代理uv可选 0.4Python 依赖管理如有 Python 源码本地开发# 1. 安装依赖buninstall# 2. 初始化数据库bun run db:push# 3. 启动开发服务器bun run dev访问http://localhost:3000支持热重载。也可使用一键脚本sh.zscripts/dev.sh生产构建# 构建 Next.js 应用bun run build# 使用完整构建脚本含子服务、Python 等BUILD_ID唯一标识sh.zscripts/build.sh构建产物为/tmp/build_fullstack_${BUILD_ID}.tar.gz。部署启动将构建产物解压到部署目录后执行shstart.sh启动顺序检测并配置 Python 运行时如有启动 Next.js Standalone 服务bun server.js后台运行校验数据库文件存在性启动 mini-services如有后台运行前台启动 Caddy主进程监听81端口验证部署# 健康检查curlhttp://localhost:81/# API 自描述curlhttp://localhost:81/api/scrape# 抓取测试curl-XPOST http://localhost:81/api/scrape\-HContent-Type: application/json\-d{url: https://example.com}成功响应应包含success: true、markdown字段和统计数据。 数据模型Prisma SQLite项目预设了User和Post模型一对多关系虽然当前抓取功能不直接使用但为后续扩展如保存抓取历史、用户管理奠定基础。model User { id String id default(cuid()) email String unique name String? createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String? published Boolean default(false) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt }数据库连接采用单例模式避免 Next.js 热重载时反复创建 PrismaClient 实例。 目录结构速览firecrawl/ ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ ├── route.ts # 健康检查 │ │ │ └── scrape/route.ts # 核心抓取 API │ │ ├── globals.css # 火焰主题 │ │ ├── layout.tsx # 根布局 SEO │ │ └── page.tsx # 首页组装所有区块 │ ├── components/ │ │ ├── firecrawl/ # 8 个业务组件 │ │ └── ui/ # shadcn/ui 40 基础组件 │ ├── hooks/ # use-mobile, use-toast │ └── lib/ │ ├── db.ts # Prisma 单例 │ ├── html-to-markdown.ts # 转换器 │ └── utils.ts # 类名工具 ├── prisma/ │ └── schema.prisma ├── examples/websocket/ # WebSocket 聊天示例 ├── mini-services/ # 子服务目录 ├── .zscripts/ # 构建与部署脚本 ├── Caddyfile # 反向代理配置 ├── next.config.ts └── package.json 火焰主题设计系统项目使用一套鲜明的视觉语言定义在globals.css中类名作用实现.fire-gradient-text橙红渐变文字linear-gradientbackground-clip: text.fire-gradient-bg橙红渐变背景linear-gradient(135deg, #fb923c, #f97316, #ef4444).fire-glow大范围火焰光晕双层box-shadow橙色 红色.fire-grid透视网格背景双向渐变 径向mask-image渐隐.fire-radial径向火焰光双椭圆radial-gradient叠加动画flame-flicker2.6s 呼吸循环和float-up粒子向上飘升加载骨架屏使用shimmer橙色高光扫过。 总结Firecrawl不仅是一个功能完整的网页抓取工具更是一个技术演示的范本前端展示与交互设计精良采用现代 React 生态后端抓取链路清晰自定义转换算法轻量高效部署架构兼顾生产环境需求通过 Caddy Standalone 模式实现一体化交付丰富的 API 能力搜索、抓取、交互使其成为 LLM 应用的数据源利器。无论是想快速搭建自己的“网页转 Markdown”服务还是学习项目的架构与部署这个项目都值得深入研究和借鉴。