Crawl4AI C4A-Script 交互式教程详解本地运行、脚本实战与服务端编译实现【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiC4A-Script 是 Crawl4AI 内置的面向 Web 自动化的人类可读脚本语言而仓库中的交互式教程位于 docs/md_v2/apps/c4a-script/提供了一套完整的 Web 端学习环境代码编辑器、Blockly 可视化编程、操作录制与实时执行可视化。本文以该教程文档为主体覆盖从本地部署、Playground 练习、五级进阶章节与五个示例脚本的完整讲法并结合 server.py、crawl4ai/script/c4a_compile.py 与 crawl4ai/async_configs.py 等源码说明脚本从 C4A 文本到可执行 JavaScript 的编译链路帮助你既能在浏览器里练会 C4A-Script也能把它直接接入 Crawl4AI 的爬虫配置中使用。教程定位与核心能力这份交互式教程的目标是让学习者“边写边跑”左侧编写 C4A-Script右侧在内置的 Playground 网页中实时执行并观察效果。根据教程文档其核心能力包括文本编辑器编写 C4A-Script带语法高亮可视化编辑器基于 Blockly 的拖拽式积木编程可视化积木与文本脚本双向同步录制模式Recording Mode捕获你在浏览器预览区的操作自动生成 C4A-Script 命令实时执行脚本实时运行并给出即时反馈时间线视图Timeline View可视化并编辑自动化步骤。教程界面还配备带语法高亮与实时编译的Live Code Editor、可查看/编辑生成结果的JavaScript Output Viewer、以及带元素高亮与控制台输出的Visual Execution执行视图并提供一批预置示例脚本Cookie 横幅处理、登录流程、无限滚动、多步表单等。本地运行教程前置条件Python 3.7现代浏览器Chrome、Firefox、Safari、Edge启动步骤教程是一个基于 Flask 的小型 Web 应用依赖声明在 requirements.txt 中仅flask2.3.0与flask-cors4.0.0。按以下步骤在本地运行# 1. 进入教程目录仓库内路径 cd docs/md_v2/apps/c4a-script/ # 2. 安装依赖 pip install -r requirements.txt # 3. 启动服务 python server.py # 4. 浏览器访问 # http://localhost:8000服务启动后终端会打印一个带边框的横幅标明服务地址、可用功能以及 C4A 编译器是否可用可用时显示 “✓ Available”否则回退到内置的 mock 编译器。官方文档站也提供免安装的在线演示可在不克隆仓库的情况下体验同一套界面。从源码结构看server.py 中端口读取的是环境变量PORT默认 8000且以host0.0.0.0、debugTrue启动。如果 8000 端口被占用可参考教程给出的处理方式# 结束占用端口的进程或换用其他端口 lsof -ti:8000 | xargs kill -9 # 或通过环境变量换端口 PORT8001 python server.py仓库内的实际文件结构教程目录的布局与文档中的架构描述一致docs/md_v2/apps/c4a-script/ ├── server.py # Flask 应用服务器 编译 API ├── requirements.txt # 依赖flask、flask-cors ├── index.html # 教程主界面 ├── test_blockly.html # Blockly 测试页 ├── blockly-demo.c4a # Blockly 演示脚本 ├── assets/ # 教程前端资源 │ ├── app.js # 主应用逻辑 │ ├── c4a-blocks.js # 自定义 Blockly 积木定义 │ ├── c4a-generator.js # 代码生成 │ ├── blockly-manager.js # Blockly 集成管理 │ └── styles.css # 主样式 ├── playground/ # 交互式演示环境 │ ├── index.html # 演示 Web 应用 │ ├── app.js # 演示应用逻辑 │ └── styles.css # 演示样式 └── scripts/ # 示例 C4A 脚本01~05Playground用于练习的动态演示站教程内置的 Playground 是一个刻意做成“复杂”的演示网页专门覆盖自动化中最常遇到的交互形态认证系统带校验的登录表单、会话管理、受保护内容动态内容无限滚动加载的商品列表、分页控件、“加载更多”按钮复杂表单多步向导、动态字段显隐、表单校验交互元素Tabs、手风琴、弹窗/模态框、可展开内容数据表格可排序列、搜索功能、导出选项。教程预置的四个示例脚本由服务端/api/examples接口下发分别对应Cookie 横幅与新闻弹窗处理、登录流程、无限滚动加载商品、多步调查表单。示例脚本直接指向 Playground例如# Handle cookie banner and newsletter GO http://127.0.0.1:8000/playground/ WAIT body 2 IF (EXISTS .cookie-banner) THEN CLICK .accept IF (EXISTS .newsletter-popup) THEN CLICK .close注意仓库中 scripts/ 目录下的 03、05 号示例脚本里写的是http://127.0.0.1:8080/playground/而服务默认监听 8000 端口实际运行前可按本地端口自行调整。C4A-Script 语法从基础命令到流程控制教程的语法教学分为三层基础命令、控制流、进阶特性。基础命令类别命令用法导航GO urlGO playground/等待WAITWAIT selector timeout或WAIT seconds点击CLICKCLICK selector输入TYPETYPE text滚动SCROLLSCROLL DOWN/UP amount教程给出的第一段脚本演示了最基本的交互模式# Basic interaction GO playground/ WAIT body 2 IF (EXISTS .cookie-banner) THEN CLICK .accept CLICK #start-tutorial语法约定与核心语言文档docs/md_v2/core/c4a-script.md一致#开头为注释CSS 选择器写在反引号内#id、.class、button[typesubmit]文本内容用双引号包裹超时秒数直接写数字。控制流条件IF (condition) THEN action条件中常用EXISTS/NOT EXISTS判断元素是否存在循环REPEAT (action, condition)可指定重复次数或退出条件过程PROC name ... ENDPROC定义可复用的命令序列之后像普通命令一样调用。进阶特性JavaScript 求值EVAL code用于读取状态、打日志或执行任意 JS变量SET name value使用时以$name引用复杂选择器任意 CSS 选择器均可放在反引号中如option[valuetech]、a[href#forms]。教程四个章节逐级进阶的脚本写法教程正文按四个部分组织每部分给出可运行的 C4A 片段。第 1 章入门学习基本命令与语法GO https://example.com WAIT .content 5 CLICK .button第 2 章处理动态内容掌握等待策略与条件判断IF (EXISTS .popup) THEN CLICK .close WAIT .results 10第 3 章表单自动化填写并提交表单CLICK #email TYPE userexample.com CLICK button[typesubmit]第 4 章复杂工作流使用过程PROC封装可复用的登录序列PROC login CLICK #username TYPE $username CLICK #password TYPE $password CLICK #login-btn ENDPROC SET username demo SET password pass123 login五个示例脚本逐段解析scripts/ 目录下有五个递进式示例是教程“动手验证”环节的素材也对应练习挑战的答案脚本01-basic-interaction.c4a基础页面交互处理 Cookie 横幅与新闻弹窗再点击开始按钮。完整脚本见 01-basic-interaction.c4a# Navigate to the playground GO http://127.0.0.1:8080/playground/ # Wait for page to load WAIT body 2 # Handle cookie banner if present IF (EXISTS .cookie-banner) THEN CLICK .accept # Close newsletter popup if it appears WAIT 3 IF (EXISTS .newsletter-popup) THEN CLICK .close # Click the start tutorial button CLICK #start-tutorial要点每个可能异步出现的干扰元素都先用WAIT留出加载时间再用IF (EXISTS ...)做存在性判断后才点击——这是全篇贯穿的防御式写法。02-login-flow.c4a完整登录流程演示表单交互与登录后的状态验证02-login-flow.c4a# Complete Login Flow # Click login button CLICK #login-btn # Wait for login modal WAIT .login-form 3 # Fill in credentials CLICK #email TYPE demoexample.com CLICK #password TYPE demo123 # Check remember me IF (EXISTS #remember-me) THEN CLICK #remember-me # Submit form CLICK button[typesubmit] # Wait for success WAIT .welcome-message 5 # Verify login succeeded IF (EXISTS .user-info) THEN EVAL console.log(✅ Login successful!)注意最后一行用IF EVAL console.log做“断言式”验证把执行结果显式打到控制台便于在教程的执行视图中确认流程是否成功。03-infinite-scroll.c4a无限滚动加载全部商品这是最能体现 C4A-Script 表达力的一个脚本03-infinite-scroll.c4a用PROC封装“滚动一次 检测是否新增了商品”再用REPEAT带条件地循环直到没有新商品加载为止# Switch to infinite scroll mode CLICK #infinite-scroll-btn # Define scroll procedure PROC load_more_products # Get current product count EVAL window.initialCount document.querySelectorAll(.product-card).length # Scroll down SCROLL DOWN 1000 WAIT 2 # Check if more products loaded EVAL const newCount document.querySelectorAll(.product-card).length; console.log(Products loaded: newCount); window.moreLoaded newCount window.initialCount; ENDPROC # Load products until no more REPEAT (load_more_products, window.moreLoaded ! false) # Final count EVAL console.log(✅ Total products: document.querySelectorAll(.product-card).length)这里的技巧在于把“是否还有新内容”写成页面全局变量window.moreLoadedREPEAT的条件直接引用它——C4A-Script 通过EVAL与页面 JS 运行时之间留了双向通道。04-multi-step-form.c4a多步表单向导覆盖跨步骤填写、多选选项与最终提交验证04-multi-step-form.c4a# Navigate to forms section CLICK a[href#forms] WAIT #survey-form 2 # Step 1: Basic Information CLICK #full-name TYPE John Doe CLICK #survey-email TYPE john.doeexample.com CLICK .next-step WAIT 1 # Step 2: Select Interests CLICK #interests CLICK option[valuetech] CLICK option[valuemusic] CLICK option[valuetravel] CLICK .next-step WAIT 1 # Step 3: Review and Submit IF (EXISTS #submit-survey) THEN EVAL console.log( On final step) CLICK #submit-survey WAIT .success-message 5 IF (EXISTS .success-message) THEN EVAL console.log(✅ Survey submitted successfully!)每切换一步都WAIT 1给前端渲染留缓冲并在提交前用IF (EXISTS ...)确认当前处于最后一步防止步骤错位。05-complex-workflow.c4a完整电商工作流把登录、浏览、筛选、Tab 切换、表格搜索与导出串成一条端到端流程展示了PROC定义与调用的完整用法05-complex-workflow.c4a# Define reusable procedures PROC handle_popups IF (EXISTS .cookie-banner) THEN CLICK .accept IF (EXISTS .newsletter-popup) THEN CLICK .close ENDPROC PROC login_user CLICK #login-btn WAIT .login-form 2 CLICK #email TYPE demoexample.com CLICK #password TYPE demo123 CLICK button[typesubmit] WAIT .welcome-message 5 ENDPROC PROC browse_products CLICK #catalog-link WAIT .product-grid 3 CLICK .collapsible WAIT 0.5 CLICK input[typecheckbox] SCROLL DOWN 500 WAIT 1 SCROLL DOWN 500 WAIT 1 ENDPROC # Main workflow GO http://127.0.0.1:8080/playground/ WAIT body 2 # Handle initial popups handle_popups # Login if not already IF (NOT EXISTS .user-info) THEN login_user # Browse products browse_products ... # Final navigation to data tables CLICK a[href#data] WAIT .data-table 2 CLICK .search-input TYPE User CLICK .load-more-rows WAIT 1 CLICK #export-btn EVAL console.log(✅ Workflow completed successfully!)亮点是IF (NOT EXISTS.user-info) THEN login_user先判断是否已登录未登录才走登录过程——这是用条件分支实现幂等流程的典型模式。五项练习挑战教程用五个由浅入深的挑战验收学习效果正好对应上面五个示例脚本Cookie 与弹窗处理页面加载时出现的 Cookie 横幅和新闻订阅弹窗完成登录使用演示凭据成功登录加载全部商品用无限滚动加载目录中的全部 100 个商品多步调查完整完成多步调查表单完整工作流编写一个“登录后浏览商品并导出数据”的组合脚本。编写技巧与排错四条实用技巧1. 使用精确选择器# Good - specific CLICK button.submit-order # Bad - too generic CLICK button2. 始终处理弹窗# Check for common popups IF (EXISTS .cookie-banner) THEN CLICK .accept IF (EXISTS .newsletter-modal) THEN CLICK .close3. 在交互前加入合适的等待# Wait for elements before interacting WAIT .form 5 CLICK #submit4. 用过程实现复用PROC handle_popups IF (EXISTS .popup) THEN CLICK .close IF (EXISTS .cookie-banner) THEN CLICK .accept ENDPROC # Use anywhere handle_popups常见错误排查现象排查思路“Element not found”点击前先加WAIT检查选择器是否过于宽泛用IF (EXISTS ...)先验证元素“Timeout waiting for selector”调大超时值确认元素是否动态加载核对选择器是否正确“Missing THEN keyword”所有IF都必须带THEN格式IF (condition) THEN action服务端排错方面端口占用可按上文换端口Blockly 加载失败时检查浏览器控制台 JS 报错、静态资源是否被正确伺服、脚本加载顺序是否正确录制功能异常时检查 iframe 权限、跨域通信与事件监听是否挂载。调试时可按教程建议打开DEBUG详细日志。从 C4A 文本到 JavaScript服务端编译链路教程的“实时编译”能力背后是 server.py 暴露的 HTTP API。从源码结构看实际提供的相关端点为GET /— 教程主界面GET /playground/— 交互式演示环境POST /api/compile— C4A 编译接口接收{script: ...}成功时返回jsCodeJS 语句列表与metadata失败时返回带line、column、message、suggestion、code、sourceLine的结构化错误GET /api/examples— 返回预置示例脚本列表静态资源/assets/...与/playground/...。编译逻辑分两条路径真实编译器server.py启动时尝试from crawl4ai.script import compile as c4a_compile。成功时每个脚本都交给 Crawl4AI 官方的C4ACompiler见 crawl4ai/script/c4a_compile.py。该编译器采用“结果模式”——不抛异常统一返回CompilationResultsuccess/js_code/errors并为常见错误分配了固定错误码错误码含义E001缺少THENmissing_thenE002缺少括号missing_parenE003缺少逗号missing_commaE004缺少ENDPROCmissing_endprocE005调用了未定义的过程undefined_procE006缺少反引号missing_backticksE007无效命令invalid_commandE999通用语法错误syntax_error这解释了教程中“Missing THEN keyword”这类提示的来源——编译失败时前端拿到的正是ErrorDetail中的行号、列号、错误信息与修改建议。Mock 编译器演示回退当仓库不可导入时server.py内建一个轻量mock_compile逐行识别GO/WAIT/CLICK/TYPE/SCROLL/IF/PRESS并直接生成 Playwright 风格的 JS例如WAITbody2会被编译为await page.waitForSelector(body, { timeout: 2000 });相对路径的GO playground/会被补全为/playground/。未知命令或缺少THEN的IF会返回带行号的错误对象。它仅用于保证演示可用性命令覆盖面远小于真实编译器不支持PROC、REPEAT、EVAL、SETVAR等。把 C4A-Script 接入 Crawl4AI在教程中练熟脚本之后可以直接用CrawlerRunConfig的c4a_script参数把脚本喂给爬虫from crawl4ai import AsyncWebCrawler, CrawlerRunConfig config CrawlerRunConfig( urlhttps://example.com, c4a_script WAIT .content 5 IF (EXISTS .load-more) THEN CLICK .load-more WAIT .new-content 3 ) async with AsyncWebCrawler() as crawler: result await crawler.arun(configconfig)这条链路在源码中可以完整对上CrawlerRunConfig在 crawl4ai/async_configs.py 中声明了c4a_script: Union[str, List[str]]参数初始化时若提供了c4a_script且未显式提供js_code会自动触发_compile_c4a_script()async_configs.py#L1904-L1906。该方法async_configs.py#L1948-L1979支持字符串或字符串列表多段脚本依次编译并拼接 JS 语句编译失败时把首条错误的行号、列号、消息与修改建议格式化成明确的C4A Script compilation error报错编译成功则把js_code写入配置由浏览器执行。因此c4a_script与js_code的关系是“源与产物”给了js_code时以js_code为准给了c4a_script时自动编译。前端关键组件与二次开发教程前端由三大组件构成文档“Developer Guide”一节TutorialAppassets/app.js主控制器负责 CodeMirror 代码编辑器集成、脚本执行与浏览器预览、教程章节导航、状态管理与持久化BlocklyManagerassets/blockly-manager.js可视化编程接口包含自定义 C4A-Script 积木定义、可视化积木与文本脚本的双向同步、实时代码生成与深色主题集成录制系统负责浏览器事件捕获、智能事件分组与过滤、自动 C4A-Script 生成与时间线可视化。若要给教程新增一条 C4A 命令文档给出的扩展路径是三步在 assets/c4a-blocks.js 中定义积木、在 assets/c4a-generator.js 中补生成器、再更新解析器blockly-manager。样式主题集中在 assets/styles.css通过 CSS 自定义属性实现主题变量并按系统偏好自动切换深色模式。服务端的运行参数默认 8000 端口、调试模式在server.py中配置详见上文启动章节。小结与延伸阅读这套教程的价值在于把 C4A-Script 的语法学习、动态页面处理技巧等待策略、条件分支、过程复用、基于EVAL的状态检测和服务端编译机制放在同一个闭环里浏览器里写、Playground 里跑、控制台上验证。教程练成的脚本无需任何改造即可通过CrawlerRunConfig.c4a_script接入 Crawl4AI 的抓取流程由crawl4ai/async_configs.py中的自动编译逻辑转成 JavaScript 在浏览器中执行。继续深入可参考仓库内的C4A-Script 语言指南完整的命令分类、选择器与变量用法、最佳实践C4A-Script API 参考逐条命令的详细文档crawl4ai/script/c4a_compile.py 与 crawl4ai/script/c4ai_script.py编译器实现与错误码体系docs/examples/c4a_script/更多自动化脚本示例Amazon、GitHub 搜索等真实站点案例。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
阅读完成 · 觉得有帮助?