# Map Remote

> 使用 Proxyman 的 Map Remote 将匹配的 HTTP、HTTPS 和 WebSocket 请求重定向到其他主机、端口或路径，例如 localhost 或预发布（staging）环境。

## 1. 这是什么？ {#1-whats-it}

Map Remote（**⌥⌘R**）可根据你设定的规则，将 HTTP 请求的地址改为新的目标服务器。客户端获取到的响应来自新服务器，就像什么都没有改变一样。

Map Remote 还支持 HTTP 与 HTTPS 之间的相互映射。

![Proxyman Map Remote 窗口，包含 Localhost 到 Production、Staging 到 Production 以及一条正则规则](https://proxyman.com/docs/assets/proxyman-map-remote-rules.jpg)

_Map Remote 规则_

> **备注:** 在 HTTP <-> HTTPS 之间映射时，请参阅常见的 [Map Remote 配置](https://proxyman.com/docs/zh-cn/advanced-features/map-remote#7-common-usages)。

> **备注:** 从 Proxyman 4.3.0 开始，Map Remote 支持 WebSocket 和 Secure WebSocket。

## 2. 优势 {#2-benefits}

* 在开发环境网站中调用部分接口的生产环境地址，无需修改源代码
* 在生产环境网站中调用开发环境的接口
* 将特定请求 URL 发送到不同的目标地址
* 实时替换请求的各个组成部分，例如协议、主机、端口、路径或查询参数

> **备注:** 想要提高效率，你可以使用 [Scripting 功能](https://proxyman.com/docs/zh-cn/scripting/script#1-whats-it)，通过编写简单的 JavaScript 代码实现与 Map Remote 相同的效果。
>
> 例如，[将 Production 切换为 Localhost 服务器的代码片段](https://proxyman.com/docs/zh-cn/scripting/snippet-code#change-request-destination-scheme-host-port-path)

## 3. 为 GraphQL 请求使用 Map Remote {#3-map-remote-with-graphql-requests}

从 Proxyman 2.27.0 及更高版本开始，Map Remote 可以通过指定的 QueryName 处理 GraphQL 请求。请参阅以下 GraphQL 文档。

- [GraphQL 调试](https://proxyman.com/docs/zh-cn/advanced-features/graphql)

## 4. 使用 Scripting 实现 Map Remote ✅ {#4-using-scripting-as-map-remote-}

如果 Map Remote 规则较难设置，你可以使用 [Scripting 工具](https://proxyman.com/docs/zh-cn/scripting/script#1-whats-it)更轻松地完成。

请参阅 [Map Remote 代码片段](https://proxyman.com/docs/zh-cn/scripting/snippet-code#8-map-remote-with-scripting)，了解如何使用 Scripting 实现与 Map Remote 相同的效果。

例如，使用 Scripting 可以轻松实现以下操作：

* 将 v1 接口映射到 v2 接口
* 将 Production 映射到 Localhost
* 将 Localhost 映射到 Production
* ...

## 5. 匹配规则 {#5-matching-rule}

> **备注:** 从 2.3.0 版本起，Proxyman 支持 [正则表达式](https://developer.apple.com/documentation/foundation/nsregularexpression#1965590) 和通配符。请参阅[如何使用通配符和正则表达式](https://proxyman.com/docs/zh-cn/basic-features/regex)。

你可以使用[通配符或正则表达式](https://proxyman.com/docs/zh-cn/basic-features/regex)定义匹配规则。

对于匹配的请求，Proxyman 会尝试：

* 如果已设置协议、主机、端口、路径和查询参数，则替换为对应的值
* 如果某个组成部分为空，则保持匹配请求中该部分不变

![Proxyman Map Remote 规则编辑器，将 http://localhost:3000/* 映射到 https://httpbin.proxyman.app](https://proxyman.com/docs/assets/proxyman-map-remote-rule-editor.jpg)

_Map Remote 规则编辑器_

> **备注:**
>
> * 文本框留空，即保持匹配请求中该部分不变
> * Map To 字段中不允许使用通配符

### 调试 {#debugging}

要查看哪条 Map Remote 规则匹配了你的 URL，请打开请求的 Summary 标签页：

1. 选择你的请求
2. 打开 **Summary** 标签页 -> **Debugging Tools**
3. 查看映射后的 URL

### 保留 Host 请求头 {#preserve-host-header}

默认情况下，Proxyman 会将 Host 请求头覆盖为 Map Remote 中的新主机。大多数请求需要这样处理才能成功。

如果希望保留原始的 Host 请求头，请在创建新条目时勾选 “Preserve Host Header” 复选框。Proxyman 将保留原有的 Host 值。

## 6. 使用方法 {#6-how-to-use}

* 右键点击选中的请求 -> **Tools** -> **Map Remote…**。Proxyman 会自动从所选请求中填入所需数据。

![从请求创建 Map Remote 规则](https://proxyman.com/docs/assets/proxyman-map-remote-context-menu.jpg)

_从请求创建 Map Remote 规则_

## 7. 常见用法 {#7-common-usages}

### 7.1 将 Localhost（HTTP）映射到 Production（HTTPS） {#71-map-localhost-http-to-production-https}

**结果：**

| 原始 URL                                            | 目标 URL                                          |
| --------------------------------------------------- | ------------------------------------------------- |
| http://localhost:3000                               | https://proxyman.io                               |
| http://localhost:3000/pricing                       | https://proxyman.io/pricing                       |
| http://localhost:3000/v1/user?id=123\&name=proxyman | https://proxyman.io/v1/user?id=123\&name=proxyman |
| **POST** http://localhost:3000/login                | **POST** https://proxyman.io/login                |

### 7.2 将 Production（HTTPS）映射到 localhost（HTTP） {#72-map-production-https-to-localhost-http}

| 原始 URL                                          | 目标 URL                                            |
| ------------------------------------------------- | --------------------------------------------------- |
| https://proxyman.io                               | http://localhost:3000                               |
| https://proxyman.io/v1/user?id=123\&name=proxyman | http://localhost:3000/v1/user?id=123\&name=proxyman |
| **POST** https://proxyman.io/login                | **POST** http://localhost:3000/login                |

### 7.3 将特定 URL 映射到其他主机 {#73-map-certain-url-to-another-host}

* 规则：**https://proxyman.io/v1/user**（例如）
* 选择 **Any** 和 **Wildcard**
* **取消勾选 Include all subpaths of this URL：** 取消勾选即表示不映射其他子路径

**Map To：**

* 协议：**https**
* 主机：新主机（例如 staging.proxyman.io）
* 端口：**443**（你的本地端口）
* 将 Path 和 Query 留空

**结果：**

| 原始 URL                                          | 目标 URL                                                  |
| ------------------------------------------------- | --------------------------------------------------------- |
| https://proxyman.io                               | https://proxyman.io（不匹配该规则）                       |
| https://proxyman.io/v2/setting                    | https://proxyman.io/v2/setting（不匹配该规则）            |
| https://proxyman.io/v1/user?id=123\&name=proxyman | https://staging.proxyman.io/v1/user?id=123\&name=proxyman |

### 7.4 将 localhost 的 WebSocket 映射到 Production {#74-map-websocket-from-localhost-to-production}

| 原始 URL                      | 目标 URL                            |
| ----------------------------- | ----------------------------------- |
| ws://localhost:4000           | wss://ws.postman-echo.com           |
| ws://localhost:4000/websocket | wss://ws.postman-echo.com/websocket |

### 7.5 将 Production 的 WebSocket 映射到 localhost {#75-map-websocket-from-production-to-localhost}

| 原始 URL                            | 目标 URL                      |
| ----------------------------------- | ----------------------------- |
| wss://ws.postman-echo.com           | ws://localhost:3000           |
| wss://ws.postman-echo.com/websocket | ws://localhost:3000/websocket |

## 了解更多 {#learn-more}

* [为测试将 API 接口从 Production 环境切换到 localhost 环境](https://proxyman.com/posts/2025-01-10-switch-api-endpoint-from-localhost-to-production-environment)