JS 渲染和浏览器控制

了解如何使用 render 参数，以及如何在网页爬虫API 中定义浏览器指令，以便爬取复杂的动态页面。

JavaScript 渲染

如果你要抓取的页面使用 JavaScript 将数据加载到 DOM 中，请在你的请求中添加 render 参数。页面随后会先完全渲染，然后我们再返回结果，格式有两种：

render 值	您将获得
html	完全渲染后的页面原始 HTML
png	渲染后页面的 Base64 编码截图（PNG）

如果你想抓取图片并下载，请参阅 本节.

请求示例

cURL

curl --user "USERNAME:PASSWORD" \
'https://realtime.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \\
-d '{"source": "universal", "url": "https://www.example.com", "render": "html"}'

Python

import requests
from pprint import pprint

# Structure payload.
payload = {
    'source': 'universal',
    'url': 'https://www.example.com',
    'render': 'html',
}

# Get response.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('USERNAME', 'PASSWORD'),
    json=payload,
)

# Instead of response with job status and results url, this will return the
# JSON response with the result.
pprint(response.json())

PHP

<?php

$params = [
    'source' => 'universal',
    'url' => 'https://www.example.com',
    'render' => 'html',
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "USERNAME" . ":" . "PASSWORD");

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo '错误:' . curl_error($ch);
}
curl_close($ch);

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";

            var parameters = new Dictionary<string, string>()
            {
                { "source", "universal" },
                { "url", "https://www.example.com" },
                { "render" : "html" },
            };


            var client = new HttpClient();

            Uri baseUri = new Uri("https://realtime.oxylabs.io");
            client.BaseAddress = baseUri;

            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
            requestMessage.Content = JsonContent.Create(parameters);

            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);

            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();

            Console.WriteLine(contents);
        }
    }
}

Go语言

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	payload := map[string]string{
		"source": "universal",
		"url": "https://www.example.com",
        	"render": "html",
	}

	jsonValue, _ := json.Marshal(payload)

	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://realtime.oxylabs.io/v1/queries",
		bytes.NewBuffer(jsonValue),
	)

	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)

	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

Java

package org.example;

import okhttp3.*;
import org.json.JSONObject;

public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";

    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "universal");
        jsonObject.put("url", "https://www.example.com");
        jsonObject.put("render", "html");

        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);

            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };

        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();

        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://realtime.oxylabs.io/v1/queries")
                .post(body)
                .build();

        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }

        System.exit(0);
    }

    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

Node.js

import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
  'source': 'universal',
  'url': 'https://www.example.com',
  'render': 'html'
};
const response = await fetch('https://realtime.oxylabs.io/v1/queries', {
  method: 'post',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  }
});

console.log(await response.json());

JSON

{
    "source": "universal", 
    "url": "https://www.example.com", 
    "render": "html"
}

JavaScript 渲染抓取页面需要更多时间。如果使用 Realtime 或 Proxy Endpoint 集成方式，请将客户端超时时间设置为 180 秒。

为确保最低流量消耗，我们的系统在页面渲染期间不会加载不必要的资源。

在特定页面上强制渲染

为确保成功抓取，某些特定域名的页面类型由于其动态内容需要渲染。对于这些页面，我们的系统 会自动强制渲染 即使你未设置 render 参数，因此你始终可以从这些原本难以抓取的页面获得准确、可靠的数据。

请注意，渲染任务比未渲染任务消耗更多流量。

受影响目标的完整列表维护在下面的文件中。我们希望用户在抓取以下页面时充分了解这一点：

forced-render-domains.csv

3KB

打开

如果你想禁用渲染，可以在请求中添加以下参数：

"render": ""

浏览器说明

当页面需要交互时，例如点击按钮、输入搜索词或滚动以加载更多内容，你可以定义自己的 browser_instructions 在页面渲染期间执行的

构建浏览器指令最简单的方法是该处的 AI 驱动可视化构建器 网页爬虫API Playground。了解更多 这里.

快速开始

首先，浏览器指令需要 render 参数，或者 html 还是 png，并以列表形式提供在 browser_instructions 字段中。列表中的每一项按顺序执行。

假设你想搜索 披萨盒 在网站上——将该词输入搜索框，点击搜索按钮，然后等待 5 秒让结果加载：

{
    "source": "universal",
    "url": "https://www.etsy.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "input",
            "value": "pizza boxes",
            "selector": {
                "type": "css",
                "value": "#global-enhancements-search-query"
            }
        },
        {
            "type": "click",
            "selector": {
                "type": "css",
                "value": "button[data-id='gnav-search-submit-button']"
            }
        },
        {
            "type": "wait",
            "wait_time_s": 5
        }
    ]
}

结果包含指令执行后的 HTML：

{
  "results": [
    {
      "content": "<!DOCTYPE html><html lang=\"en-US\">  \"pizza boxes\" 的搜索结果  </html>",
      "created_at": "2026-08-19 12:23:06",
      "updated_at": "2026-08-19 12:23:24",
      "page": 1,
      "url": "https://www.etsy.com/search?q=pizza+boxes&ref=search_bar&instant_download=false",
      "job_id": "7495817623108602881",
      "is_render_forced": false,
      "type": "raw",
      "status_code": 200
    }
  ]
}

抓取到的 HTML 应如下所示：

获取浏览器资源

我们提供了一个用于获取浏览器资源的独立浏览器指令。

函数定义如下：

使用 fetch_resource 将使任务返回与所提供格式匹配的第一个 Fetch/XHR 资源，而不是目标 HTML。

假设我们想定位一个 GraphQL 资源，该资源会在浏览器中自然访问商品页面时被获取。我们将这样提供任务信息：

{
    "source": "universal",
    "url": "https://www.example.com/product-page/123",
    "render": "html",
    "browser_instructions": [
        {
            "type": "fetch_resource",
            "filter": "/graphql/product-info/123"
        }
    ]
}

这些指令将得到如下结果：

{
  "results": [
    {
      "content": "{'product_id': 123, 'description': '', 'price': 123}",
      "created_at": "2023-10-11 11:35:23",
      "updated_at": "2023-10-11 11:36:08",
      "page": 1,
      "url": "https://example.com/v1/graphql/product-info/123/",
      "job_id": "7117835067442906114",
      "status_code": 200
    }
  ]
}

支持的浏览器指令列表

通用参数

下面定义的所有指令都使用一致的一组参数。参数如下。

type

• 类型: Enum["click", "input", "scroll", "scroll_to_bottom", "wait", "wait_for_element", "fetch_resource"]
• 说明： 浏览器指令类型。
• 必填: true

timeout_s

• 类型: 整数
• 说明： 如果未能在规定时间内完成，多久后跳过该操作。
• 限制: 0 < timeout_s <= 60
• 默认值: 5

wait_time_s

• 类型: 整数
• 说明： 在执行下一步操作前等待多长时间。
• 限制: 0 < wait_time_s <= 60
• 默认值: 0

on_error

• 类型: Enum["error", "skip"]
• 说明： 用于指示当此指令失败时如何处理后续指令：

  • "error"：停止浏览器指令的执行。
  • "skip"：继续执行下一条指令。
• 默认值: "error"

通用参数示例

{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5,
    "wait_time_s": 2,
    "on_error": "skip"

}

指令

click

• 描述：点击某个元素并等待指定秒数。
• 参数：

  • type: str = "click"
  • selector: dict

    • type: Enum["xpath", "css", "text"]
    • value: str

示例:

{
    "type": "click",
    "selector": {
        "type": "xpath",
        "value": "//button"
    }
}

input

• 描述：向选定元素输入文本。
• 参数：

  • type: str = "input"
  • selector: dict

    • type: Enum["xpath", "css", "text"]
    • value: str
  • value: str

示例：

{
    "type": "input",
    "selector": {
        "type": "xpath",
        "value": "//input"
    },
    "value": "pizza boxes"
}

scroll

• 描述：滚动指定像素数。
• 参数：

  • type: str = "scroll"
  • x: int
  • y: int

示例：

{
    "type": "scroll",
    "x": 0,
    "y": 100
}

scroll_to_bottom

• 描述：向下滚动到底部，持续指定秒数。
• 参数：

  • type: str = "scroll_to_bottom"

示例:

{
    "type": "scroll_to_bottom",
    "timeout_s": 10
}

wait

• 描述：等待指定秒数。
• 参数：

  • type: str = "wait"

示例:

{
    "type": "wait",
    "wait_time_s": 2
}

wait_for_element

• 描述：等待元素加载，持续指定秒数。
• 参数：

  • type: str = "wait_for_element"
  • selector: dict

    • type: Enum["xpath", "css", "text"]
    • value: str

示例：

{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5
}

fetch_resource

该 fetch_resource 该指令必须是浏览器指令列表中的最后一条；后续任何指令都不会执行。

• 描述：获取与所设模式匹配的第一个 Fetch/XHR 资源。
• 参数：

  • type: str = "fetch_resource"
  • filter: str(RegEx expression)
  • on_error: Enum["error", "skip"]

示例：

{
    "type": "fetch_resource",
    "filter": "/graphql/item/"
}

指令验证

任何关于指令格式的不一致都会导致一个 400 状态码和相应的错误消息。

例如，载荷如下：

{
    "source": "universal",
    "url": "https://www.example.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "unsupported-wait",
            "wait_time_s": 5
        }
    ]
}

将导致：

{    
    "errors": {
        "message": "不支持的操作类型 `unsupported-wait`，可从 'click,fetch_resource,input,scroll,scroll_to_bottom,wait,wait_for_element' 中选择"
    }
}

故障排查

状态码

请参见我们列出的响应代码 这里。关于指令验证的状态代码已有文档说明 这里.

错误和警告

如果你的浏览操作产生错误或警告，你会在结果中的以下键下找到它 browser_instructions_error 还是 browser_instructions_warnings。例如，如果你发送了以下浏览器指令，而预期的 xpath 未在页面上找到，结果将包含警告。

browser_instructions:

[
    {
        "type": "input", 
        "selector": {
            "type": "xpath",
            "value": "//input[@type='search']"
        },
        "value": "Oxylabs"
    }
]

结果：

{
  "results": [
    {
      "content": "<!doctype html><html>
        执行指令后的内容      
      </html>",
      "created_at": "2023-10-11 11:35:23",
      "updated_at": "2023-10-11 11:36:08",
      "browser_instructions_warnings": [
        {
          "action_type": "click",
          "msg": "无法在页面上找到值为 `//input[@type=search]` 的选择器类型 `xpath`。"
        },
      ],
      "page": 1,
      "url": "https://example.com",
      "job_id": "7117835067442906113",
      "status_code": 200
    }
  ]
}

可能的错误和警告
将浏览器指令转换为操作时发生意外错误。
执行时发生意外错误 {action.type} 浏览器指令。
操作 {action.type} 超时。
无法找到选择器类型 {selector.type} 其值为 {selector.value} 在页面上。