Quantumult 脚本编写完全指南：从入门到精通的进阶之路

引言：当网络工具遇上编程思维

在这个信息爆炸、网络环境日益复杂的时代，单纯依靠图形界面的代理工具已经难以满足高阶用户的需求。Quantumult作为iOS生态中备受推崇的网络代理工具，其魅力不仅在于稳定高效的代理能力，更在于它赋予了用户通过脚本语言“驯服”网络请求的无限可能。如果说Quantumult是一把精密的瑞士军刀，那么脚本就是用户亲手打磨的刀刃——唯有理解其锻造之法，方能发挥出真正的威力。

本文将以实操为导向，系统拆解Quantumult脚本的核心逻辑、语法结构与实战技巧，助你从“会用工具”跨越到“创造工具”的层次。无论你是刚接触脚本的新手，还是寻求进阶思路的老手，这份指南都将为你点亮前行的灯塔。

第一章：重新认识Quantumult脚本——它究竟在做什么？

在深入代码之前，我们必须建立清晰的认知：Quantumult脚本并非传统意义上的编程语言，而是一种事件驱动的规则引擎。它监听网络请求的生命周期，在特定节点（如请求发起、响应返回）触发你预设的逻辑。你可以把它想象成一个智能交通警察——每辆“网络请求”的车辆经过路口时，脚本决定是放行、改道、还是直接拦截。

这种设计哲学带来了三大核心优势： 1. 动态决策：基于请求头、URL、响应体等实时数据做出判断，而非静态规则 2. 资源优化：在设备端完成数据处理，减少不必要的流量消耗 3. 个性化定制：每个用户都能编写属于自己的“网络宪法”

第二章：脚本语法精讲——从零搭建你的第一段逻辑

2.1 脚本的“骨架”：配置段与触发条件

Quantumult脚本遵循精简的声明式结构，核心是[Script]配置段。每个脚本块由三要素构成：

[Script] http-request ^https://api\.example\.com/ script-path=scripts/rewrite.js, tag=API重写

• 匹配模式：正则表达式定义需要处理的URL模式
• 脚本路径：指向本地或远程JavaScript文件
• 标签：便于在日志中识别和管理

2.2 请求处理的“三驾马车”

Quantumult支持三类主要事件类型，各有其适用场景：

| 事件类型 | 触发时机 | 典型应用 | |---------|---------|---------| | http-request | 请求发出前 | 改写请求头、参数加密 | | http-response | 响应返回后 | 修改响应体、提取数据 | | cron | 定时任务 | 刷新Token、自动签到 |

2.3 一个完整的JavaScript脚本解剖

以最常见的“请求头改写”为例，看一段真实可运行的代码：

```javascript // 脚本：添加认证Token const request = $request; const token = "yourgeneratedtoken_here";

// 修改请求头 request.headers["Authorization"] = Bearer ${token}; request.headers["User-Agent"] = "Quantumult/1.0 (+https://example.com)";

// 完成修改 $done({ headers: request.headers }); ```

这段代码展示了Quantumult脚本的标准执行流程： 1. 通过$request获取当前请求对象 2. 对请求属性进行增删改查 3. 调用$done()返回修改后的对象，或直接中断请求

2.4 条件判断的艺术：让脚本学会思考

高级脚本的精髓在于响应式逻辑。以下示例演示如何根据响应状态码执行不同操作：

```javascript const status = $response.statusCode; const body = $response.body;

if (status === 200 && body.includes("error")) { // 检测到业务错误，重试或降级 $done({ statusCode: 500, body: JSON.stringify({error: "业务异常"}) }); } else if (/^https:\/\/video.example.com/.test($request.url)) { // 视频请求特殊处理 $done({ body: body.replace("720p", "1080p") }); } else { $done($response); // 原样返回 } ```

第三章：实战进阶——解决真实场景中的五大难题

3.1 场景一：广告请求的智能拦截

传统的URL拦截规则过于僵硬，而脚本可以结合请求上下文进行精准判断：

javascript // 拦截所有包含"ad"参数且来源为新闻客户端的请求 if ($request.url.includes("ad") && $request.headers["X-Client-Type"] === "news_app") { $done({ response: { status: 204, headers: {}, body: "" } }); } else { $done({}); }

3.2 场景二：响应体的数据清洗

当接口返回冗余数据时，脚本可以充当“数据过滤器”：

javascript // 提取JSON中的关键字段，删除无用信息 const json = JSON.parse($response.body); const cleaned = json.data.map(item => ({ id: item.id, title: item.title, timestamp: item.updated_at })); $done({ body: JSON.stringify({ data: cleaned }) });

3.3 场景三：多环境配置的动态切换

通过读取当前网络状态，实现测试与生产环境的无缝切换：

javascript const env = $request.headers["X-Env"] || "prod"; const baseURL = env === "dev" ? "https://api.dev.example.com" : "https://api.example.com"; $done({ url: $request.url.replace("https://api.example.com", baseURL) });

3.4 场景四：并发请求的合并优化

巧妙利用脚本的异步能力，减少网络开销：

javascript // 将多次请求合并为一次（需配合缓存机制） const cacheKey = $request.url; if (cache[cacheKey]) { // 命中缓存，直接返回 $done({ body: cache[cacheKey] }); } else { // 发起真实请求并缓存结果（此处为示意代码） const realResponse = await fetch($request.url); cache[cacheKey] = realResponse.body; $done({ body: realResponse.body }); }

3.5 场景五：安全防护——请求签名的动态生成

对于接口鉴权，脚本可以实时计算签名：

```javascript function generateSignature(params) { const sortedKeys = Object.keys(params).sort(); const signStr = sortedKeys.map(k => ${k}=${params[k]}).join("&"); return CryptoJS.MD5(signStr + "secret_salt").toString(); }

const params = { time: Date.now(), user_id: "12345" }; params.sign = generateSignature(params); $done({ url: $request.url + "?" + new URLSearchParams(params).toString() }); ```

第四章：调试与优化——让脚本稳定运行的必修课

4.1 日志的艺术：善用console.log

Quantumult提供了完善的日志系统，但错误的使用方式会导致调试效率低下。建议遵循以下原则： - 分级输出：用console.log记录正常流程，console.error标记异常 - 关键节点必打：请求进入、条件分支、返回结果处 - 避免冗余：不要每行代码都输出，聚焦于变量变化和决策点

4.2 性能优化：减少脚本对网络的影响

脚本运行在代理网络中，任何延迟都会被用户感知。优化建议： - 避免同步阻塞：不要使用while循环等待异步操作 - 精简正则表达式：复杂正则会导致CPU飙升，可预编译缓存 - 复用全局变量：将常用配置存放在$prefs中，避免重复计算

4.3 异常处理：让脚本在错误中优雅降级

网络环境千变万化，脚本必须拥抱异常：

javascript try { // 可能出错的操作 const data = JSON.parse($response.body); // ... 处理逻辑 } catch (e) { // 出错时返回原始响应，保证功能可用 console.error("解析失败: " + e.message); $done($response); }

第五章：高级技巧——突破常规思维的创新应用

5.1 结合外部API，打造“智能代理”

Quantumult脚本可以发起外部请求，实现云端决策：

javascript // 调用远程规则服务 const remoteRule = await $httpClient.get("https://rules.example.com/check?url=" + encodeURIComponent($request.url)); if (remoteRule.data.block) { $done({ response: { status: 403, body: "Blocked by remote rule" } }); } else { $done({}); }

5.2 利用$prefs实现跨请求状态管理

通过共享存储，实现登录状态、用户偏好等持久化数据：

```javascript // 存储用户Token $prefs.setValueForKey("user_token", "abc123");

// 读取Token const token = $prefs.valueForKey("user_token"); ```

5.3 响应式UI：脚本与Quantumult界面联动

高级脚本可以动态生成配置菜单，提升用户体验：

javascript // 通知用户脚本执行结果 $notification.post("脚本提示", "请求已重写", "成功添加认证头");

第六章：常见错误与规避策略——从踩坑到填坑

错误一：忘记调用$done()导致请求挂起

解决方案：始终保证脚本所有路径都能执行$done()，建议在函数末尾统一处理。

错误二：正则表达式过于宽泛导致误匹配

解决方案：用^和$锚定边界，尽量使用非贪婪匹配，并配合URL结构限定范围。

错误三：修改请求体但未更新Content-Length

解决方案：修改body后，同步更新headers中的Content-Length字段，否则服务器会报错。

错误四：异步操作未正确处理

解决方案：使用async/await或Promise链，确保$done()在异步操作完成后调用。

结语：脚本是工具，思维是灵魂

Quantumult脚本的学习曲线并非陡峭，但它的能力边界完全取决于你的想象力。当你掌握基础语法后，真正的挑战在于如何将网络协议知识、业务逻辑和编程技巧融合在一起，设计出优雅而高效的解决方案。

记住，每一个脚本都是你对网络世界的一次“立法”。它可能小到只修改一个请求头，也可能大到构建一套完整的流量治理系统。但无论规模如何，都遵循着同样的原则：明确目标、精准匹配、最小干预、优雅降级。

希望这篇指南能成为你探索Quantumult脚本世界的起点。当你在深夜调试代码时，那些不断闪烁的日志，不仅是数据流的印记，更是你与数字世界对话的语言。现在，打开Quantumult，写下你的第一行脚本吧——网络的大门，正为你敞开。