untun 隧道实战：从入门到精通

2026-03-10 04:46:44作者：余洋婵Anita

核心功能解析

什么是隧道技术？

隧道技术（Tunnel）就像在互联网上搭建一条专用通道，让本地服务器能够安全地暴露到公网。想象一下，你在自己家里建了一个小型服务器（比如开发中的网站），但想让外面的人也能访问，这时候就需要通过隧道工具来实现。untun 正是这样一款基于 Cloudflare Quick Tunnels 的高效工具，能够帮助开发者轻松将本地 HTTP(s) 服务器安全地暴露到公网。

untun 的核心组件

untun 的核心功能主要通过以下几个关键文件实现：

src/tunnel.ts：隧道创建与管理的主接口，提供了高层级的隧道操作方法。
src/cloudflared/tunnel.ts：Cloudflare 隧道实现细节，负责与 Cloudflare 服务进行底层交互。
src/cloudflared/service.ts：隧道服务管理工具，提供了安装、卸载、监控等服务管理功能。

隧道选项接口（TunnelOptions）

在使用 untun 创建隧道之前，我们需要了解如何配置隧道选项。TunnelOptions 接口提供了灵活的参数配置方式：

export interface TunnelOptions {
  url?: string;           // 本地服务器URL，如未指定则由其他参数组合生成
  port?: number | string; // 本地服务器端口，默认为3000
  hostname?: string;      // 本地服务器主机名，默认为localhost
  protocol?: "http" | "https"; // 协议类型，默认为http
  verifyTLS?: boolean;    // 是否验证TLS证书，开发环境可设为false
  acceptCloudflareNotice?: boolean; // 是否自动接受Cloudflare条款
}

适用场景：根据不同的开发需求，灵活配置隧道参数。例如，在本地开发环境中，可以设置 verifyTLS: false 来禁用 TLS 验证，降低配置复杂度；而在生产环境中，则应该启用 TLS 验证以确保安全性。

隧道实例接口（Tunnel）

创建隧道后会返回一个 Tunnel 对象，它提供了操作隧道的核心方法：

export interface Tunnel {
  getURL: () => Promise<string>; // 获取隧道公网URL
  close: () => Promise<void>;    // 关闭隧道连接
}

适用场景：通过 getURL 方法可以获取公网访问地址，用于测试或分享；当不再需要隧道时，调用 close 方法可以关闭隧道连接，释放资源。

使用流程详解

1. 准备工作

首先，需要克隆 untun 仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/un/untun
cd untun
npm install

2. 创建基本隧道

以下是一个基本的隧道创建和使用示例，包含了错误处理和资源清理：

import { startTunnel } from './src/tunnel';

async function createBasicTunnel() {
  // 配置隧道选项
  const tunnelOptions = {
    port: 3000,          // 指定本地服务器端口为3000
    protocol: "http",    // 使用HTTP协议
    verifyTLS: false     // 开发环境禁用TLS验证
  };

  let tunnel;
  try {
    // 启动隧道
    tunnel = await startTunnel(tunnelOptions);
    
    if (tunnel) {
      // 获取公网URL
      const publicUrl = await tunnel.getURL();
      console.log(`隧道已启动，公网访问地址: ${publicUrl}`);
      
      // 模拟业务逻辑运行
      console.log("隧道正在运行，按Ctrl+C停止...");
      await new Promise(resolve => process.on('SIGINT', resolve));
    }
  } catch (error) {
    console.error("隧道操作出错:", error);
  } finally {
    // 确保隧道在退出前关闭
    if (tunnel) {
      try {
        await tunnel.close();
        console.log("隧道已关闭");
      } catch (closeError) {
        console.error("关闭隧道时出错:", closeError);
      }
    }
  }
}

createBasicTunnel();

代码解析：

我们使用 startTunnel 函数创建隧道，传入配置选项。
通过 try-catch-finally 结构确保错误能够被捕获，并且隧道能够正确关闭。
使用 process.on('SIGINT', resolve) 监听用户的中断信号，以便在用户按下 Ctrl+C 时优雅地关闭隧道。

3. 高级隧道配置

对于更复杂的场景，可以直接使用底层的 startCloudflaredTunnel 函数，它提供了更灵活的配置选项：

import { startCloudflaredTunnel } from './src/cloudflared/tunnel';

async function createAdvancedTunnel() {
  // 配置高级隧道选项
  const tunnelOptions = {
    "--url": "http://localhost:3000",  // 本地服务器地址
    "--no-tls-verify": "",             // 禁用TLS验证
    "--metrics": "localhost:4040"      // 启用 metrics 服务
  };

  // 启动底层隧道
  const tunnel = startCloudflaredTunnel(tunnelOptions);
  
  try {
    // 获取公网URL
    const publicUrl = await tunnel.url;
    console.log(`高级隧道已启动，公网访问地址: ${publicUrl}`);
    
    // 监听隧道进程的退出事件
    tunnel.child.on('exit', (code) => {
      console.log(`隧道进程退出，代码: ${code}`);
    });
    
    // 模拟长时间运行
    await new Promise(resolve => setTimeout(resolve, 30000));
  } catch (error) {
    console.error("高级隧道操作出错:", error);
  } finally {
    // 停止隧道
    tunnel.stop();
    console.log("高级隧道已停止");
  }
}

createAdvancedTunnel();

代码解析：

startCloudflaredTunnel 函数接受一个选项对象，其中可以包含各种 cloudflared 命令行参数。
该函数返回一个对象，包含隧道 URL 的 Promise、连接信息、子进程对象和停止方法。
我们可以通过监听子进程的 exit 事件来处理隧道意外退出的情况。

进阶技巧

隧道服务管理

src/cloudflared/service.ts 提供了一系列工具函数，帮助管理隧道服务的生命周期：

install() - 安装 Cloudflare 隧道组件
uninstall() - 卸载 Cloudflare 隧道组件
exists() - 检查隧道组件是否已安装
log() - 获取隧道服务日志
clean() - 清理隧道服务残留文件

适用场景：在生产环境中，可能需要将隧道服务设置为开机自启动，这时候就可以使用这些服务管理函数。

环境变量配置

可以通过环境变量预先接受 Cloudflare 服务条款，避免交互式确认：

export UNTUN_ACCEPT_CLOUDFLARE_NOTICE=true

适用场景：在自动化部署或 CI/CD 流程中，使用环境变量可以实现无人值守的隧道部署。

错误处理最佳实践

安装确认：首次使用时，用户需要确认接受 Cloudflare 的服务条款，可以通过 acceptCloudflareNotice: true 参数自动接受。
资源清理：确保在程序退出时调用 tunnel.close() 方法，避免资源泄漏。可以使用 process.on('SIGINT', ...) 来监听退出信号。
错误捕获：使用 try/catch 块捕获隧道操作可能抛出的异常，如网络错误、权限问题等。
日志记录：在生产环境中，可以将隧道日志输出到文件，便于问题排查。