企业官网建设流程全解析

HarmonyOS 7 Agent 时代来了：本地 DevEco Demo 怎么用 cpolar 发给同事手机远程联调？

HarmonyOS 7 发布后，“Agent 时代”很容易成为讨论焦点。但做 Demo 时，开发者经常遇到更实际的问题：DevEco 项目在本机跑通了，本地 mock API 也写好了，同事想用自己的手机看流程，却不在同一个局域网。

这篇只解决一个具体场景：把开发机上的本地接口用 cpolar 临时映射成 HTTPS 地址，让外地同事的手机也能访问你的 DevEco Demo 联调接口。本文只面向开发环境，演示结束后关闭隧道，不暴露生产接口、数据库端口和管理后台。

1 什么是 DevEco 本地联调？

DevEco Studio 里写 HarmonyOS Demo 时，页面通常需要接口数据。真实后端还没准备好，或者字段还在调整，就会先在开发机上启动一个 mock 服务，例如http://127.0.0.1:3000。

自己在电脑上调试很顺，但同事手机访问不了这个地址。127.0.0.1只代表当前设备自己，同事手机上的127.0.0.1指向同事的手机，不是你的电脑。

同一个办公室里，可以让电脑和手机连同一个 Wi-Fi，再用电脑局域网 IP 访问。异地协作时，这条路走不通。cpolar 在这里负责把本地3000端口生成公网 HTTPS 地址，同事手机访问该地址，请求再回到你的本机 mock 服务。

2 环境准备：DevEco、Node.js 和 cpolar

开始前准备这些环境：

• 开发机已安装 DevEco Studio，并能运行 HarmonyOS Demo
• Node.js 18 或更高版本，用来启动本地 mock API
• cpolar 客户端，用来创建临时 HTTP 隧道
• 一台手机或模拟器，用来确认 Demo 页面请求正常

先检查 Node.js：

node -v npm -v

macOS 可以用 Homebrew 安装 cpolar：

brew tap probezy/core && brew install cpolar sudo cpolar service install sudo cpolar service start cpolar version curl -s http://127.0.0.1:9200 || echo "cpolar 服务未启动"

Linux 开发机可以使用官方一键脚本：

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash

安装完成后打开http://127.0.0.1:9200登录账号。能看到 cpolar Web UI，说明本机服务已经启动。这里建议先不要创建太多隧道，本文只需要一个 HTTP 隧道。配置越少，后面定位问题越快。

如果公司电脑限制了服务安装，可以先让管理员协助启动 cpolar 服务，再继续下面的联调步骤。不要跳过本地控制台验证，因为后面拿不到公网地址时，最常见的原因就是客户端服务没有正常运行。

3 启动一个本地 mock API

为了让流程完整，这里用 Express 起一个最小接口。接口返回 Demo 首页需要的卡片数据，DevEco 项目只负责请求并展示。

mkdir harmonyos-cpolar-mock cd harmonyos-cpolar-mock npm init -y npm install express cors cat > server.js <<'EOF' const express = require('express'); const cors = require('cors'); const app = express(); app.use(cors()); app.use(express.json()); app.get('/api/agent-demo', (req, res) => { res.json({ title: 'HarmonyOS Agent Demo', status: 'ready', message: '本地 mock API 已经被手机端访问到', items: [ { name: '任务理解', value: '通过' }, { name: '接口联调', value: '通过' }, { name: '远程演示', value: '通过' } ] }); }); app.listen(3000, () => { console.log('mock api listening on http://127.0.0.1:3000'); }); EOF node server.js

另开一个终端验证接口：

curl http://127.0.0.1:3000/api/agent-demo

能看到 JSON 返回，就说明本地接口可用。如果这里没有返回，先检查node server.js是否还在运行，再检查端口是不是被别的程序占用。

这一步建议保留终端窗口，不要跑完就关。后面同事手机访问 Demo 时，终端里会出现新的请求记录。看到请求进来，就能确认公网访问已经回到了你的开发机；没有请求记录，就说明问题还在隧道地址、网络访问或手机端请求配置上。

4 在 DevEco Demo 里接入接口地址

DevEco Demo 里只保留一个可切换的接口地址。后面拿到 cpolar HTTPS 地址后，只改这一处，排错会轻很多。

建议单独放一个配置文件，例如ApiConfig.ets：

export const API_BASE_URL = 'http://127.0.0.1:3000'; const url = `${API_BASE_URL}/api/agent-demo`;

如果你已经有自己的网络请求封装，就把基础地址放到同一个配置入口，不要散落在多个页面里。这里别填错协议和端口，3000要和 Express 服务监听的端口一致。

真机调试时，如果手机不能访问127.0.0.1:3000，不要在手机上继续纠结。这个地址在手机上指向手机自己，下一步直接换成 cpolar 生成的公网地址。

开发阶段还要注意缓存。改完基础地址后，重新构建并运行 Demo，确认页面没有继续使用旧地址。如果项目里做了请求封装或环境变量切换，把日志打印出来看一次，请求 URL 和接口路径必须完整一致。

5 用 cpolar 创建 HTTP 隧道

本地 mock API 已经跑在3000端口，创建 HTTP 隧道：

cpolar http 3000

命令运行后，终端会输出公网访问地址。也可以打开 cpolar Web UI，在“状态 → 在线隧道列表”里查看公网地址。

拿到 HTTPS 地址后，先用电脑验证：

curl https://你的-cpolar-地址/api/agent-demo

这里要看到和本地curl一样的 JSON。访问失败时，按这个顺序查：本地node server.js是否运行、cpolar http 3000是否在线、复制的地址是否带了完整https://、接口路径是否写成/api/agent-demo。

不要直接把首页地址发给同事就结束，先自己访问接口路径。首页能打开不代表接口路径正确，接口路径能返回 JSON，才说明手机端 Demo 有稳定的联调入口。

6 把 HTTPS 地址发给同事手机联调

把ApiConfig.ets里的基础地址改成 cpolar 的 HTTPS 地址：

export const API_BASE_URL = 'https://你的-cpolar-地址';

重新运行 DevEco Demo，确认页面请求的是新地址。然后把安装包、预览包或测试说明发给同事，让同事手机打开 Demo 页面。

同事能看到接口数据时，你的 mock 服务终端也会出现请求记录。这一步看到两边都通，才算链路完成：手机请求 cpolar 地址，cpolar 转发到你的开发机，Express 返回 JSON，Demo 页面展示数据。

如果 Demo 里有新增、删除、修改类接口，开发联调阶段建议先关掉，或者加一层简单鉴权。临时演示只开放只读接口，风险更低，排错也更简单。

同事反馈“页面空白”时，不要只看页面截图。让对方同时提供手机浏览器访问接口的结果、Demo 页面操作路径和你本机终端里的请求时间。三项信息对齐后，基本能判断是手机端请求没发出、请求地址写错，还是 mock API 返回内容不符合页面渲染逻辑。

还有一个细节别忽略：联调前先约定接口返回字段，不要一边改 mock，一边让同事反复刷新页面。字段名、状态码和空数据结构固定下来后，手机端页面更容易判断是展示问题还是接口问题。多人协作时，把 cpolar 地址、接口路径、测试账号和关闭时间写在同一条消息里，减少来回确认。

7 固定地址和安全边界怎么处理

临时协作时，随机 HTTPS 地址够用。免费随机地址适合短时演示，地址会在 24 小时内变化。团队经常联调同一个 Demo 时，可以使用固定二级子域名；固定二级子域名需要基础套餐或以上。

安全边界提前定好：

• 只暴露开发用 mock API，不暴露数据库、管理后台和生产接口
• 只开放演示需要的只读接口，写接口加鉴权或直接关闭
• 演示结束后关闭隧道，避免临时入口长期在线

如果 Demo 已经接入真实账号体系，不要把 token、密钥、Cookie 写进前端代码。联调时用测试账号和测试数据，出问题也容易回滚。

8 总结

现在我们完成了一条适合 HarmonyOS Demo 的远程联调链路：本地 DevEco 项目请求 cpolar HTTPS 地址，cpolar 把请求转回开发机上的 mock API，同事手机不需要和你在同一个局域网，也能参与页面验收。

关键步骤可以压缩成三件事：

• 本地先启动 mock API，并用curl http://127.0.0.1:3000/api/agent-demo验证
• 用cpolar http 3000创建 HTTP 隧道，再用公网 HTTPS 地址验证接口
• DevEco Demo 只改统一的API_BASE_URL，让同事手机访问同一套测试接口

等真实后端上线后，再把 Demo 的基础地址切回测试环境或生产环境；cpolar 继续保留给临时联调、Webhook 调试和远程演示使用，会更省事。