Surge Module Usage Guide

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

• v2ex-DailyBonus — auto claim coins.
• Mitm All — enable MITM for every host temporarily.
• iQIYI DailyBonus
• JD DailyBonus
• SS Subscription Info — display airport traffic usage.

Find more modules:

• https://github.com/lhie1/Rules/tree/master/Surge/Surge%203/Module
• https://github.com/yichahucha/surge

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

• https://community.nssurge.com/d/225-module
• https://community.nssurge.com/d/33-scripting
• https://github.com/chavyleung/scripts
• https://github.com/NobyDa/Script
• https://github.com/lhie1/Rules/tree/master