How to Use Surge Module (Step-by-Step Guide)

Explains what Surge modules are, how they override the base profile, debugging tips, and practical module use cases.

Aug 4, 2021 · 2 min read · 395 Words · -Views -Comments · Digital Nomad
Network Tools 🇨🇳 阅读中文版
Read with AI

Choose an AI assistant

ChatGPT Open in a new tab with the article link and prompt
Claude Copy the prompt, then open Claude

Open Claude
Trouble reading the article?

If the prompt is missing, copy the full prompt below into your AI assistant. If the AI cannot read the article, paste the visible passage you want to discuss and add your question.

I used to ignore Surge modules—installed a few community ones, never dug deeper. After reading more and experimenting, I realized they solve specific problems elegantly. Here’s what I learned.

What Is a Module?

  1. Officially, a module patches the active profile. Think of it as an overlay with limited sections (Rules, MITM, etc.). Support matrix: https://community.nssurge.com/d/225-module
  2. Module settings override the base profile. Multiple modules apply in order; later ones win.
  3. Module enable/disable states are not synced across devices (the files themselves are).
  4. Profiles now support #!include fragments, but fragments must contain entire sections. You can’t split the [Rule] block between main and fragment. Modules, however, can inject partial config.

Editing & Reloading

  • JS changes in a module take effect immediately—no restart needed.
  • Changing cron jobs requires a restart.

Debugging

Use console.log in module scripts; view logs here:

  • macOS: ~/Library/Logs/Surge/
  • iOS: Tools → Log (or Files app under Surge’s sandbox)

How I Use Modules

  1. Install community modules (e.g., CMB/JD daily check-ins). They’re great for automation and HTTP reverse engineering. Be cautious: modules can exfiltrate data—only install from trusted sources. Some require MITM; too many can hurt performance, so enable on demand.
  2. Build custom modules. Example: MitM All. When debugging an app, you might need to decrypt all hosts temporarily; doing that via rules is tedious. With a module you can toggle full MITM on/off quickly.

Installed Modules

Find more modules:

After editing a module, restart Surge for changes to apply.

Example: JD DailyBonus

Follow module instructions:

  1. Visit https://bean.m.jd.com (MITM must be enabled).
  2. You’ll see a notification that a cookie was stored.
  3. Cron jobs will run the sign-in automatically.

How it works: the module grabs cookies from the intercepted HTTPS request and saves them. Cron scripts then call the API at scheduled times.

Automating Module Toggles

  • macOS: use the Alfred workflow to enable/disable modules via Surge API.
  • iOS: use Shortcuts + Surge’s “Run Script” action.

Common Errors

  1. invalid module — check device restrictions (#!system=Mac fails on iPhone).
  2. Failed to load detached section… — on iOS, use iCloud Drive for profile sync.

Final Thoughts

Surge is powerful but has a learning curve. Modules are developer-oriented, yet they unlock a lot once you grasp the basics.

References

Authors
Developer, digital product enthusiast, tinkerer, sharer, open source lover