How to Configure Proxy Settings for Network Requests in PicList-Core

To configure proxy settings in PicList-Core, set the picBed.proxy configuration key via the CLI (picgo proxy -p <url>) or programmatically, and the Request class will automatically route all upload traffic through the specified proxy.

PicList-Core (from the kuingsmile/piclist-core repository) implements a centralized proxy configuration system that intercepts all network requests. When you configure proxy settings for network requests, the framework reads this value, converts it to an Axios-compatible proxy object, and injects it into every upload operation, including specialized handling for HTTPS-over-HTTP tunneling.

Where Proxy Configuration is Stored

The proxy setting persists under the configuration key picBed.proxy. This value can be set through the built-in CLI command defined in src/plugins/commander/proxy.ts, which registers the -p, --proxy <url> flag:

// src/plugins/commander/proxy.ts
cmd.program.option('-p, --proxy <url>', 'set proxy for uploading', (proxy: string) => {
  ctx.setConfig({ 'picBed.proxy': proxy })
})

When executed, this command writes the proxy URL directly to the user’s configuration store, making it available for all subsequent network operations.

How the Proxy is Applied to Network Requests

The Request class in src/lib/Request.ts manages proxy application through three distinct mechanisms:

Initialization

Upon instantiation, the Request constructor reads the current configuration:

// src/lib/Request.ts (init)
private init(): void {
  const proxy = this.ctx.getConfig<Undefinable<string>>('picBed.proxy')
  if (proxy) {
    this.proxy = proxy
  }
}

Runtime Updates

If the configuration changes while the application is running, an event listener updates the internal proxy field dynamically:

// src/lib/Request.ts (listener)
eventBus.on(IBusEvent.CONFIG_CHANGE, (data) => {
  switch (data.configName) {
    case 'picBed':
      if ((data.value as IConfig['picBed'])?.proxy) {
        this.proxy = (data.value as IConfig['picBed']).proxy
      }
      break
    case 'picBed.proxy':
      this.proxy = data.value as string
      break
  }
})

Request-Time Processing

Before each HTTP request, the handleProxy() method parses the stored string into an Axios-compatible object:

// src/lib/Request.ts (handleProxy)
private handleProxy(): AxiosRequestConfig['proxy'] | false {
  if (this.proxy) {
    try {
      const proxyOptions = new URL(this.proxy)
      return {
        host: proxyOptions.hostname,
        port: parseInt(proxyOptions.port || '0', 10),
        protocol: proxyOptions.protocol,
      }
    } catch {}
  }
  return false
}

For HTTPS destinations tunneled through HTTP proxies, the implementation configures a specialized agent:

// src/lib/Request.ts (request)
this.options.proxy = this.handleProxy()
…
if (this.options.proxy && options.url?.startsWith('https://')) {
  this.options.httpsAgent = httpsOverHttp({
    proxy: {
      host: this.options.proxy.host,
      port: this.options.proxy.port,
    },
  })
  this.options.proxy = false
}

Configuration Methods

Using the CLI Command

The simplest way to configure proxy settings for network requests is via the built-in proxy command:

picgo proxy -p http://127.0.0.1:1080

This writes the value to picBed.proxy in your configuration file.

Programmatic Configuration

For plugin development or custom integrations, set the configuration directly through the PicGo context:

import PicGo from 'piclist-core'

const ctx = new PicGo()
ctx.setConfig({ 'picBed.proxy': 'http://127.0.0.1:1080' })

Removing the Proxy

To disable proxy routing, delete the configuration key:

picgo config delete picBed.proxy

Summary

• PicList-Core stores proxy settings under the picBed.proxy configuration key
• The Request class in src/lib/Request.ts automatically applies these settings to every upload request
• Configuration supports both CLI (-p, --proxy) and programmatic (ctx.setConfig) methods
• HTTPS-over-HTTP proxying is handled automatically via the httpsOverHttp agent
• Runtime configuration changes are detected and applied without requiring a restart

Frequently Asked Questions

What URL format should I use for the proxy setting?

PicList-Core accepts standard URL formats such as http://127.0.0.1:1080 or http://username:password@proxy.example.com:8080. The handleProxy() method in src/lib/Request.ts parses this using the Node.js URL constructor, extracting the hostname, port, and protocol fields for the Axios configuration.

Does PicList-Core support HTTPS proxies?

Yes. When the target upload URL uses HTTPS, the framework automatically creates an httpsOverHttp agent using the proxy host and port, then sets this.options.proxy = false to prevent double-proxying. This ensures secure connections route correctly through your HTTP proxy.

Will proxy settings apply to all upload requests automatically?

Yes. Once picBed.proxy is configured, every network request made through the Request class will include the proxy configuration. This covers all uploads performed via picgo upload commands or programmatic API calls using the core request library.

How do I verify the proxy is working?

Check your proxy server logs for incoming connections from PicList-Core during uploads, or enable debug logging in your application. The framework applies the proxy immediately after configuration changes through the IBusEvent.CONFIG_CHANGE event listener, so changes take effect on the next request without requiring a restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}