chrome.proxy

refresh date: 2026-09-25 robots: noindex

شرح

از میانای برنامه‌سازی کاربردی chrome.proxy برای مدیریت تنظیمات پراکسی Chrome استفاده کنید. این میانای برنامه‌سازی کاربردی برای دریافت و تنظیم پیکربندی پراکسی به نمونه اولیه ChromeSetting از نوع میانای برنامه‌سازی کاربردی متکی است.

اجازه‌ها

proxy

مانیفست

برای استفاده از API تنظیمات پراکسی، باید اجازه «پراکسی» را در مانیفست افزونه اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "proxy"
  ],
  ...
}

اشیاء و خصوصیت‌ها

تنظیمات پراکسی در شیء proxy.ProxyConfig تعریف می‌شود. بسته به تنظیمات پراکسی Chrome، تنظیمات ممکن است حاوی proxy.ProxyRules یا proxy.PacScript باشد.

حالت‌های پراکسی

مشخصه mode شیء ProxyConfig رفتار کلی Chrome را دررابطه‌با استفاده از پراکسی تعیین می‌کند. می‌تواند مقادیر زیر را داشته باشد:

direct
در حالت direct، همه اتصال‌ها مستقیماً و بدون دخالت پراکسی ایجاد می‌شوند. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد.
auto_detect
در حالت auto_detect، پیکربندی پراکسی توسط دستورگان PAC تعیین می‌شود که می‌توان آن را از http://wpad/wpad.dat بارگیری کرد. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد.
pac_script
در حالت pac_script، پیکربندی پراکسی توسط دستورگان PAC تعیین می‌شود که یا از نشانی وب مشخص‌شده در شیء proxy.PacScript بازیابی می‌شود یا به‌طور دقیق از عنصر data مشخص‌شده در شیء proxy.PacScript گرفته می‌شود. علاوه‌براین، این حالت پارامترهای بیشتری را در شیء ProxyConfig مجاز نمی‌کند.
fixed_servers
در حالت fixed_servers، پیکربندی پراکسی در شیء proxy.ProxyRules کدگذاری می‌شود. ساختار آن در قوانین پراکسی شرح داده شده است. علاوه‌براین، حالت fixed_servers اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد.
system
در حالت system، پیکربندی پراکسی از سیستم‌عامل گرفته می‌شود. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد. توجه داشته باشید که حالت system با تنظیم نکردن پیکربندی پراکسی متفاوت است. در حالت دوم، Chrome فقط درصورتی به تنظیمات سیستم برمی‌گردد که هیچ گزینه خط فرمانی بر پیکربندی پراکسی تأثیر نگذارد.

قوانین پراکسی

شیء proxy.ProxyRules می‌تواند حاوی مشخصه singleProxy یا زیرمجموعه‌ای از proxyForHttp، proxyForHttps، proxyForFtp، و fallbackProxy باشد.

در حالت اول، ترافیک HTTP،‏ HTTPS، و FTP ازطریق سرور پراکسی مشخص‌شده پراکسی می‌شود. ترافیک دیگر مستقیماً ارسال می‌شود. در حالت دوم، رفتار کمی ظریف‌تر است: اگر یک سرور پراکسی برای پروتکل HTTP،‏ HTTPS، یا FTP پیکربندی شده باشد، ترافیک مربوطه ازطریق سرور مشخص‌شده پراکسی می‌شود. اگر چنین پراکسی سروری مشخص نشده باشد یا ترافیک از پروتکلی غیراز HTTP،‏ HTTPS، یا FTP استفاده کند، از fallbackProxy استفاده می‌شود. اگر هیچ fallbackProxy مشخص نشده باشد، ترافیک مستقیماً بدون پراکسی سرور ارسال می‌شود.

اشیای پراکسی سرور

سرور پروکسی در شیء proxy.ProxyServer پیکربندی شده است. اتصال به سرور پراکسی (تعریف‌شده با مشخصه host) از پروتکل تعریف‌شده در مشخصه scheme استفاده می‌کند. اگر هیچ scheme مشخص نشده باشد، اتصال پراکسی به‌طور پیش‌فرض روی http تنظیم می‌شود.

اگر هیچ port در شیء proxy.ProxyServer تعریف نشده باشد، درگاه از طرح مشتق می‌شود. درگاه‌های پیش‌فرض عبارت‌اند از:

طرحدرگاه
http80
https443
socks41080
socks51080

فهرست فرعی

سرورهای تکی ممکن است از پراکسی شدن با bypassList مستثنی شوند. این فهرست ممکن است حاوی ورودی‌های زیر باشد:

[SCHEME://]HOST_PATTERN[:PORT]

با همه نام‌های میزبانی که با الگوی HOST_PATTERN مطابقت دارند مطابقت داشته باشد. ‫"." پیشرو به‌عنوان "*." تفسیر می‌شود.

مثال‌ها: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

الگوموارد منطبقمطابقت ندارد
".foobar.com""www.foobar.com""foobar.com"
"*.foobar.com""www.foobar.com""foobar.com"
"foobar.com""foobar.com""www.foobar.com"
"*foobar.com""foobar.com"، "www.foobar.com"، "foofoobar.com"
[SCHEME://]IP_LITERAL[:PORT]

نشانی‌های وبی را که نشانی IP واقعی هستند مطابقت دهید. ازنظر مفهومی، این مورد مشابه مورد اول است، اما با موارد خاصی برای رسیدگی به متعارف‌سازی تحت‌اللفظی IP. برای مثال، مطابقت با «[0:0:0::1]» با مطابقت با «[::1]» یکسان است زیرا متعارف‌سازی IPv6 به‌صورت داخلی انجام می‌شود.

مثال‌ها: 127.0.1، [0:0::1]، [::1]:80، https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

با هر نشانی وبی که حاوی نشانی IP واقعی (IP_LITERAL) در محدوده داده‌شده باشد مطابقت دارد. محدوده IP (PREFIX_LENGTH_IN_BITS) بااستفاده از نشان‌گذاری CIDR مشخص شده است.

با هر نشانی وبی که حاوی IP literal در محدوده داده‌شده باشد مطابقت دارد. محدوده IP بااستفاده از نماد CIDR مشخص می‌شود. مثال‌ها: "192.168.1.1/16", "fefe:13::abc/33"

<local>

رشته تحت‌اللفظی <local> با نام‌های میزبان ساده مطابقت دارد. نام میزبان ساده نامی است که نقطه ندارد و به‌صورت IP نوشته نشده است. برای مثال، example و localhost نام‌های میزبان ساده هستند، درحالی‌که example.com، example.، و [::1] این‌طور نیستند.

مثال: "<local>"

مثال‌ها

کد زیر یک پراکسی SOCKS 5 برای اتصالات HTTP به همه سرورها به‌جز foobar.com تنظیم می‌کند و از اتصالات مستقیم برای همه پروتکل‌های دیگر استفاده می‌کند. تنظیمات برای پنجره‌های معمولی و ناشناس اعمال می‌شود، زیرا پنجره‌های ناشناس تنظیمات را از پنجره‌های معمولی به‌ارث می‌برند. لطفاً به اسناد Types API نیز مراجعه کنید.

var config = {
  mode: "fixed_servers",
  rules: {
    proxyForHttp: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
chrome.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

کد زیر یک اسکریپت PAC سفارشی را تنظیم می‌کند.

var config = {
  mode: "pac_script",
  pacScript: {
    data: "function FindProxyForURL(url, host) {\n" +
          "  if (host == 'foobar.com')\n" +
          "    return 'PROXY blackhole:80';\n" +
          "  return 'DIRECT';\n" +
          "}"
  }
};
chrome.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

قطعه کد بعدی تنظیمات پراکسی مؤثر فعلی را پُرسمان می‌کند. تنظیمات پراکسی مؤثر را می‌توان با افزونه دیگری یا با خط‌مشی تعیین کرد. برای جزئیات، به مستندات Types API مراجعه کنید.

chrome.proxy.settings.get(
  {'incognito': false},
  function(config) {
    console.log(JSON.stringify(config));
  }
);

توجه داشته باشید که شیء value که به set() ارسال شده است با شیء value که به تابع بازخوانی get() ارسال شده است یکسان نیست. مورد دوم حاوی عنصر rules.proxyForHttp.port خواهد بود.

انواع

Mode

Chrome نسخه ۵۴ و بالاتر

شمارشی

"direct"

"auto_detect"

"pac_script"

"fixed_servers"

"system"

PacScript

شیئی که اطلاعات پیکربندی خودکار پراکسی را نگه می‌دارد. دقیقاً یکی از فیلدها باید خالی نباشد.

مشخصات

  • داده

    رشته اختیاری

    یک اسکریپت PAC.

  • اجباری

    بولی اختیاری

    اگر درست باشد، اسکریپت PAC نامعتبر مانع از بازگشت پشته شبکه به اتصالات مستقیم می‌شود. پیش‌فرض: نادرست.

  • نشانی وب

    رشته اختیاری

    نشانی وب فایل PAC که باید استفاده شود.

ProxyConfig

شیئی که پیکربندی کامل پراکسی را کپسوله‌سازی می‌کند.

مشخصات

  • حالت حمل‌ونقل

    حالت

    «direct» = هرگز از پراکسی استفاده نشود «auto_detect» = تنظیمات پراکسی به‌طور خودکار شناسایی شود «pac_script» = از PAC script مشخص‌شده استفاده شود «fixed_servers» = سرورهای پراکسی به‌طور دستی مشخص شود «system» = از تنظیمات پراکسی سیستم استفاده شود

  • pacScript

    PacScript اختیاری

    اسکریپت پیکربندی خودکار پراکسی (PAC) برای این پیکربندی. از این برای حالت «pac_script» استفاده کنید.

  • قوانین

    ProxyRules اختیاری

    قوانین پراکسی که این پیکربندی را شرح می‌دهد. از این برای حالت «fixed_servers» استفاده کنید.

ProxyRules

شیئی که مجموعه قوانین پراکسی را برای همه پروتکل‌ها کپسوله می‌کند. از «singleProxy» یا (زیرمجموعه‌ای از) «proxyForHttp»،‏ «proxyForHttps»،‏ «proxyForFtp»، و «fallbackProxy» استفاده کنید.

مشخصات

  • bypassList

    رشته[] اختیاری

    فهرست سرورهایی که بدون پراکسی سرور به آن‌ها متصل می‌شوید.

  • fallbackProxy

    ProxyServer اختیاری

    سرور پروکسی که برای همه موارد دیگر استفاده می‌شود یا اگر هرکدام از proxyFor... خاص مشخص نشده باشد.

  • proxyForFtp

    ProxyServer اختیاری

    سرور پراکسی که برای درخواست‌های FTP استفاده می‌شود.

  • proxyForHttp

    ProxyServer اختیاری

    پراکسی سرور برای استفاده در درخواست‌های HTTP.

  • proxyForHttps

    ProxyServer اختیاری

    پراکسی سرور برای استفاده در درخواست‌های HTTPS.

  • singleProxy

    ProxyServer اختیاری

    پراکسی سروری که برای همه درخواست‌های هر نشانی وب (یعنی http،‏ https، و ftp) استفاده می‌شود.

ProxyServer

شیئی که مشخصات یک پراکسی سرور را کپسوله می‌کند.

مشخصات

  • میزبان

    رشته

    نام میزبان یا نشانی IP پراکسی سرور. نام‌های میزبان باید در قالب ASCII (در قالب Punycode) باشد. IDNA هنوز پشتیبانی نمی‌شود.

  • درگاه

    شماره اختیاری

    درگاه پراکسی سرور. به‌طور پیش‌فرض به درگاهی می‌رود که به طرح بستگی دارد.

  • طرح‌واره

    طرح اختیاری

    طرح (پروتکل) خود پراکسی سرور. پیش‌فرض: «http».

Scheme

Chrome نسخه ۵۴ و بالاتر

شمارشی

"http"

"https"

"quic"

"socks4"

"socks5"

مشخصات

settings

تنظیمات پراکسی که باید استفاده شود. مقدار این تنظیم یک شیء ProxyConfig است.

نوع

types.ChromeSetting<ProxyConfig>

رویدادها

onProxyError

chrome.proxy.onProxyError.addListener(
  callback: function,
)

خطاهای پراکسی را اطلاع می‌دهد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • جزئیات

        رشته

        جزئیات بیشتر درباره خطا، مثل خطای زمان اجرای جاوا اسکریپت.

      • خطا

        رشته

        توضیح خطا.

      • مهلک

        بولی

        اگر درست باشد، خطا مهلک بوده و تراکنش شبکه لغو شده است. درغیراین‌صورت، از اتصال مستقیم استفاده می‌شود.