Ngrok 配置：实现 Uniapp 前后端项目内网穿透

文章目录

- 一、下载并安装 ngrok
- 二、配置 ngrok Authtoken
- 三、启动本地 uniapp 项目
- 四、使用 ngrok 暴露本地服务
- 五、通过公网 URL 访问项目
- 六、后端API项目的穿透问题排查 (uni-app + 后端 API 示例)
- - 交互流程图示
- 七、ngrok Web 界面 (本地监控)
- 八、停止 ngrok
- 总结

ngrok 是一款强大的工具，可以让你将本地运行的 web 服务暴露到公网上，非常适合用于本地开发调试、向客户演示项目或测试 webhook 等场景。

一、下载并安装 ngrok

访问 ngrok 官网下载页面：https://ngrok.com/download
下载 Windows 版本的 ngrok
解压 ngrok：将下载的 ngrok.zip 文件解压到一个你方便访问的目录，解压后你会得到一个 ngrok.exe 文件。

二、配置 ngrok Authtoken

为了使用 ngrok 的更多功能（例如自定义子域名等，尽管某些高级功能可能需要付费），建议连接到你的 ngrok 账户。

登录 ngrok 官网：访问 https://dashboard.ngrok.com/。
获取 Authtoken：在仪表盘的 “Your Authtoken” 或 “Setup & Installation” 部分，你会找到你的 Authtoken。
配置 Authtoken：
- 运行ngrok.exe
- 运行以下命令（将 YOUR_AUTHTOKEN 替换为你自己的 Authtoken）：
```
.\ngrok.exe config add-authtoken YOUR_AUTHTOKEN
```
- 成功后，ngrok 会将 Authtoken 保存到其默认的配置文件中 (通常在 C:\Users\YourUserName\.ngrok2\ngrok.yml)。
可选：将 ngrok添加到系统环境变量 (PATH)
为了在任何目录下都能直接运行 ngrok 命令，而不是每次都 cd 到其所在目录，你可以将其路径添加到系统环境变量 PATH 中。
1. 在 Windows 搜索中搜索"环境变量"，选择"编辑系统环境变量"。
2. 在"系统属性"窗口中，点击"系统变量(N)…"按钮。
3. 在"系统变量"区域找到名为 Path 的变量，选中它，然后点击"编辑(E)…"。
4. 点击"新建(N)"，然后输入 ngrok.exe 所在的目录路径 (例如 D:\tools\ngrok)。
5. 一路点击"确定"保存更改。之后新打开的命令行窗口即可直接使用 ngrok 命令。
- (截图机会：展示添加环境变量的步骤)

三、启动本地 uniapp 项目

接下来，我们需要一个在本地运行的 web 服务。这里以 uniapp H5 项目为例。

进入 uniapp 项目目录：使用命令行工具 (CMD, PowerShell, Git Bash 等) cd 到你的 uniapp 项目根目录。
启动开发服务器：运行 uniapp 的 H5 开发命令。
- 如果使用 npm:
```
npm run dev:h5
```
- 如果使用 yarn:
```
yarn dev:h5
```
记录本地地址和端口：项目启动后，命令行通常会显示 H5 预览地址，例如 http://localhost:8080 或 http://127.0.0.1:3000。记下这个端口号，我们稍后会用到。

四、使用 ngrok 暴露本地服务

现在，我们将使用 ngrok 将本地运行的 uniapp 项目暴露到公网上。

新建域并启动
启动隧道，运行 ngrok 命令：
获取公网URL：ngrok 启动后，会在命令行界面显示一些信息，最重要的就是 Forwarding 中的https:// 开头的 URL，这就是你的公网访问地址。

五、通过公网 URL 访问项目

现在，你或你的朋友、同事、客户等，可以在任何有网络连接的设备上，通过浏览器打开上一步中 ngrok 生成的 Forwarding URL (通常建议使用 https 的那个)，就能访问到你本地运行的 uniapp 项目了，到这里对于未配置后端的项目来说已经穿透成功了。

六、后端API项目的穿透问题排查 (uni-app + 后端 API 示例)

当你使用 uni-app 开发前端，并需要连接到一个独立的后端 API 服务（例如 Java Spring Boot, Node.js 等）时，通过 ngrok 暴露前端后，可能会遇到 API 请求失败的问题。本地直接访问 localhost:UNIAPP_DEV_PORT (uni-app H5 运行的端口) 时一切正常，但通过 ngrok 生成的公网 URL 访问时，后端接口调用不通。

常见现象:

浏览器开发者工具的网络(Network)标签页显示 API 请求失败，错误可能是 net::ERR_CONNECTION_REFUSED。
或者，如果后端没有正确配置CORS，可能会看到跨域相关的错误信息。

主要原因及解决方案 (针对绝对 BASE_URL 配置):

假设你的 uni-app 项目中，API 请求的基础路径 BASE_URL 是一个写死的本地地址，例如：

// 在 api/index.js 或类似文件中
const BASE_URL = 'http://localhost:8080/api'; // 你的后端API基础路径

问题核心：localhost 指向的是客户端
- 当你的同学或同事通过 ngrok 的公网 URL (例如 https://xxxx.ngrok.io) 访问你的 uni-app 应用时，应用内的 JavaScript 代码（包括 API 请求）是在他们的浏览器中执行的。
- 因此，代码中对 http://localhost:8080/api 的请求，实际上是尝试连接他们自己电脑上的 localhost:8080 服务。如果他们的电脑上没有运行对应的后端服务，这个请求自然会失败。
解决方案：为后端 API 服务也启动 ngrok
- 步骤1: 确保后端服务正常运行：首先，确保你的 Spring Boot (或其他) 后端服务正在你的开发机器上的 localhost:8080 (或你配置的任何端口) 成功运行。
- 步骤2: 为后端启动单独的 ngrok 实例：打开一个新的命令行窗口，cd 到 ngrok.exe 所在的目录（或者如果已配置环境变量，直接运行），然后为你的后端服务端口启动 ngrok。如果后端运行在 8080 端口：
```
ngrok http 8080
```
- ngrok 会为你的后端服务生成另一个公网 URL，例如 https://yyyy.ngrok.io。
- 步骤3: (临时) 修改前端的 BASE_URL：回到你的 uni-app 项目代码，在 api/index.js (或类似文件) 中，将 BASE_URL 临时修改为 ngrok 为后端生成的公网地址：
```
// 临时修改，用于公网演示
const BASE_URL = 'https://yyyy.ngrok.io/api'; // 注意：这里是后端 ngrok 的地址
```
- 步骤4: 重新编译 uni-app 项目 (如果需要)，并确保访问前端 ngrok 地址的用户获取到的是更新了 BASE_URL 的前端代码。
- 现在，通过前端 ngrok URL 访问应用时，API 请求就会正确地指向你通过 ngrok 暴露的公网后端服务了。
后端 CORS 配置:
- 非常重要！你的后端服务（如 Spring Boot）必须配置 CORS (跨源资源共享) 策略，以允许来自你的前端 ngrok URL (例如 https://xxxx.ngrok.io) 和后端 ngrok URL (https://yyyy.ngrok.io，如果请求来源是它) 的请求。否则，即使地址正确，浏览器也可能因为安全策略阻止请求。
- 在 Spring Boot 中，通常使用 @CrossOrigin注解或全局 CORS 配置。

替代方案 (推荐用于开发和更便捷的共享): 使用代理

虽然上述方法可行，但每次共享都需要修改 BASE_URL 并可能需要重新部署前端，比较繁琐。更推荐的做法是在 uni-app 开发服务器层面设置代理，将特定的 API 请求转发到本地后端。

前端 BASE_URL 使用相对路径:

// api/index.js
const BASE_URL = '/api_proxy'; // 一个自定义的代理前缀
// ... 确保请求方法中 url 拼接正确，例如： request({ url: options.url ...}) 变成 request({ url: BASE_URL + options.url ...})
// 如果 options.url 已经是 /resource/action, 那么拼接后就是 /api_proxy/resource/action

配置 vue.config.js (uni-app H5 项目根目录):
如果项目根目录下没有 vue.config.js 文件，新建一个。

// vue.config.js
module.exports = {devServer: {proxy: {'/api_proxy': { // 匹配前端以 /api_proxy 开头的请求target: 'http://localhost:8080', // 你的本地后端服务地址changeOrigin: true, // 必须，用于支持跨域pathRewrite: {'^/api_proxy': '/api' // 将请求路径中的 /api_proxy 替换为 /api (如果后端是以 /api 开头的)// 例如 /api_proxy/users/list -> http://localhost:8080/api/users/list}}}}
};

修改 vue.config.js 后，需要重启 uni-app 开发服务器 (npm run dev:h5)。

ngrok 暴露 uni-app 开发服务器: 这种情况下，你只需要像之前一样，用 ngrok 暴露 uni-app H5 运行的端口 (例如 ngrok http UNIAPP_DEV_PORT)。uni-app 的开发服务器会自动将 /api_proxy 的请求转发到你的本地后端。这样，前端代码中的 BASE_URL 无需改动，分享也更方便。

交互流程图示

下面通过图示来进一步说明两种主要配置下的工作流程。

(一) 绝对 BASE_URL + 前后端分别使用 Ngrok (推荐用于需要固定公网后端地址的场景)

这种配置下，前端代码中的 BASE_URL 直接指向后端 ngrok 的公网地址。

解释:

用户 (自己或他人)：通过 https://frontend.ngrok.io (前端的公网 ngrok 地址) 访问应用。
前端应用加载后，其 API 请求直接指向 https://backend.ngrok.io/api (后端的公网 ngrok 地址)。
这种方式清晰地分离了前端和后端的公网访问点。

(二) 相对 BASE_URL + Uni-app devServer.proxy + 前端使用 Ngrok (推荐用于开发调试和便捷分享)

这种配置下，前端代码中的 BASE_URL 是一个相对路径 (如 /api_proxy)，由 Uni-app 开发服务器代理到本地后端。

解释:

用户 (自己或他人)：通过 https://frontend.ngrok.io 访问应用。
前端应用加载后，其 API 请求 (例如 /api_proxy/users) 被发送到 https://frontend.ngrok.io/api_proxy/users。
这个请求到达开发者的 Uni-app 开发服务器后，其内部的代理设置会将此请求转发给实际运行在 localhost:portB 的后端服务。
这种方式下，只需要为前端启动一个 ngrok 实例，配置相对简单。

通用排查提示:

确认后端服务已启动并监听正确端口：这是最基本的一步。
直接测试后端接口：使用 Postman、curl 或直接在浏览器中（如果接口支持GET）访问你的本地后端接口 (例如 http://localhost:8080/api/some-endpoint)，确保它能正常工作并返回数据。如果本地都访问不通，ngrok 自然也无法使其工作。

通过以上步骤，应该能解决大部分 ngrok 穿透后 API 请求失败的问题。