Features

Opt-in URL rewrite rules. When configured, PicGo applies URL rewrite after uploader execution and before afterUploadPlugins.

• type: Array<Rule>
• default: not set (no rewrite; no warnings)

Each rule supports:

• match (string, required): JavaScript RegExp source (no surrounding /).
• replace (string, required): Replacement string (supports $1, $2, ...).
• enable (boolean, optional): defaults to true; only explicit false disables the rule.
• global (boolean, optional): maps to the regex g flag; defaults to false.
• ignoreCase (boolean, optional): maps to the regex i flag; defaults to false.

Behavior:

• Rules are evaluated in array order; first enabled match wins (only one rule is applied per image).
• If rewrite changes imgUrl, PicGo stores the original URL in originImgUrl (set once and never overwritten).
• Invalid regex patterns are logged and skipped without failing the upload.
• If a rewrite produces an empty string, PicGo logs a warning and continues.

For plugin authors and Node.js users

• afterUploadPlugins will see the rewritten imgUrl in ctx.output; use originImgUrl to access the original URL produced by the uploader.
• picgo.upload() (Node.js API) returns IImgInfo[] with the rewritten imgUrl; use originImgUrl if you need the pre-rewrite value.
• originImgUrl is only set when PicGo actually rewrites the URL; otherwise it stays undefined.

Examples

Example (simple prefix rewrite / switch to CDN):

Rewrite:

• https://example.com/images/2026/1.png
• → https://cdn.example.com/blog-images/2026/1.png

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "https://example.com/images/",
          "replace": "https://cdn.example.com/blog-images/"
        }
      ]
    }
  }
}

Example (ignore case: normalize file extension):

Rewrite:

• https://cdn.example.com/blog-images/2026/1.PNG
• → https://cdn.example.com/blog-images/2026/1.png

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "PNG",
          "replace": "png",
          "ignoreCase": true
        }
      ]
    }
  }
}

Example (global: replace all underscores in the URL):

Rewrite:

• https://cdn.example.com/blog_images/2026/hello_world.png
• → https://cdn.example.com/blog-images/2026/hello-world.png

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "_",
          "replace": "-",
          "global": true
        }
      ]
    }
  }
}

TIPS: Regex and escaping

match is a JavaScript regular expression source. For advanced patterns, you may need to escape backslashes in JSON strings, e.g., \\. for a literal dot.

Advanced: capture groups ($1, $2, ...)

Rewrite:

• https://example.com/images/2026/1.png
• → https://cdn.example.com/blog-images/2026/1.png

If your match uses parentheses to capture parts of the URL, you can reference them in replace (e.g. $1 for the first group, $2 for the second). In this example, $1 is the captured images, and $2 is the rest of the path (2026/1.png):

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "^https://example.com/(images)/(.*)$",
          "replace": "https://cdn.example.com/blog-$1/$2"
        }
      ]
    }
  }
}

Advanced example (rewrite GitHub raw URLs to jsDelivr):

Rewrite:

• https://raw.githubusercontent.com/user/repo/main/path/to/1.png
• → https://cdn.jsdelivr.net/gh/user/repo@main/path/to/1.png

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "^https://raw.githubusercontent.com/([^/]+)/([^/]+)/([^/]+)/(.*)$",
          "replace": "https://cdn.jsdelivr.net/gh/$1/$2@$3/$4"
        }
      ]
    }
  }
}