# springboot-vue3-cpolar-demo
**Repository Path**: jun-wan/springboot-vue3-cpolar-demo
## Basic Information
- **Project Name**: springboot-vue3-cpolar-demo
- **Description**: 本项目用于“演示如何使用 cpolar 将本地前端穿透到公网”。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-21
## Categories & Tags
**Categories**: Uncategorized
**Tags**: Java, SpringBoot, JavaScript, HTML, Vue
## README
本项目用于“演示如何使用 cpolar 将本地前端穿透到公网”。
注意：本仓库本身不内置 cpolar 客户端与隧道配置，也不会自动开启穿透；你需要在本地安装并手动运行 cpolar（见下文步骤）。
后端仅本地运行，通过前端代理访问。
## 目录
- [目录](#目录)
- [目录结构](#目录结构)
- [快速开始](#快速开始)
- [前端启动](#前端启动)
- [前端说明](#前端说明)
- [前端：Toast 提示](#前端toast-提示)
- [前端 proxy 与 Vite 配置](#前端-proxy-与-vite-配置)
- [cpolar 访问前端](#cpolar-访问前端)
- [常见问题](#常见问题)
- [后端说明](#后端说明)
- [版本信息](#版本信息)
- [许可](#许可)
## 目录结构
```
./
├─ backend/ # Spring Boot 2 后端（本地 8888 端口）
│ ├─ pom.xml
│ └─ src/
│ ├─ main/java/com/example/cpolar/demo/
│ │ ├─ CpolarDemoApplication.java
│ │ └─ controller/TestController.java
│ └─ main/resources/application.yml
└─ frontend/ # Vue 3 + Vite 前端（开发端口 5173）
├─ package.json
├─ vite.config.js
├─ index.html
└─ src/
├─ main.js
├─ App.vue
├─ api/
│ └─ index.js # API 模块（统一管理接口）
├─ utils/
│ ├─ request.js # axios 封装（拦截器/标准化错误）
│ └─ toast.js # Toast 服务（程序式调用）
└─ components/
└─ Toast.vue # Toast 组件
```
## 快速开始
前置要求：JDK 11+、Maven 3.6+、Node.js 18+
```bash
cd backend
mvn spring-boot:run
```
- 启动后，后端监听 `http://localhost:8888`
- 测试接口：`GET http://localhost:8888/api/test`，返回示例：
```json
{
"msg": "操作成功",
"timestamp": "2025-01-01 12:00:00",
"status": "success",
"requestCount": 1
}
```
### 前端启动
前置要求：Node.js 18+ 与 npm/yarn/pnpm。
```bash
cd frontend
npm install
npm run dev
```
- 默认启动在 `http://localhost:5173`
- 页面会请求 `/api/test` 并渲染 `msg / timestamp / status / requestCount`
## 前端说明
- axios 封装：`src/utils/request.js`
- 集成请求/响应拦截器，统一标准化错误（网络超时、4xx/5xx 等）
- 导出 `httpGet(url, params, config)` 与 `httpPost(url, data, config)`
- API 模块：`src/api/index.js`
- 统一管理接口，例如：
```js
import { httpGet } from '../utils/request'
export function getTest() {
return httpGet('/api/test') // 通过 Vite 代理访问本地后端
}
```
- 组件中使用：
```js
import { getTest } from './api'
const data = await getTest()
```
## 前端：Toast 提示
- 组件：`src/components/Toast.vue`
- 服务：`src/utils/toast.js`，提供 `toast.success/info/error/warn`：
```js
import { toast } from './utils/toast'
toast.success('刷新成功')
toast.error('请求失败')
```
### 前端 proxy 与 Vite 配置
- 配置文件：`frontend/vite.config.js`
- 关键项（cpolar 公网 HTTPS 访问）：
```js
// 将 PUBLIC_DOMAIN 改为你的 cpolar 公网域名（留空则本地普通 HMR）
const PUBLIC_DOMAIN = '' // 例如：'your.cpolar.cn'
export default defineConfig({
server: {
host: true, // 监听 0.0.0.0
port: 5173, // 本地端口
https: false, // 本地保持 http，HTTPS 由 cpolar 公网侧提供
allowedHosts: [
PUBLIC_DOMAIN // 允许通过该域名访问（避免 Blocked host）
],
hmr: {
protocol: 'wss', // 热更新使用安全 WebSocket
host: PUBLIC_DOMAIN,
clientPort: 443
},
proxy: {
'/api': {
target: 'http://localhost:8888',
changeOrigin: true
}
}
}
})
```
## cpolar 访问前端
前置准备：请先在本机安装并登录 cpolar（参考官方文档）。
1. 启动后端：`cd backend && mvn spring-boot:run`（本地 `8888`）
2. 启动前端：`cd frontend && npm install && npm run dev`（本地 `5173`）
3. 打开 `frontend/vite.config.js`，将顶部 `PUBLIC_DOMAIN` 改为 cpolar 分配给你的公网域名（留空表示本地开发，不经公网域名访问）
4. 手动运行 cpolar 隧道（本仓库不负责启动）：
```bash
cpolar http 5173
```
5. 在浏览器访问 `https://你的域名.cpolar.cn`，即可打开前端页面；前端通过代理访问本地后端
## 常见问题
- Blocked request/host 不允许
- 已将你的公网域名加入 `allowedHosts`？与 `PUBLIC_DOMAIN` 一致？
- 修改后需重启 `npm run dev`
- HMR 热更新不工作
- 是否配置了 `hmr.protocol = 'wss'`、`hmr.host = PUBLIC_DOMAIN`、`hmr.clientPort = 443`（仅当设置了 `PUBLIC_DOMAIN`）？
- 浏览器控制台是否存在 `wss` 连接错误？
- 访问 502
- 确认 `server.https` 为 `false`（cpolar 负责公网侧 HTTPS 终止）
- 接口请求失败
- 后端是否已在 `8888` 启动？
- `proxy` 是否 `/api` → `http://localhost:8888`？
## 后端说明
- 接口路径：`/api/test`
- 响应字段：`msg`、`timestamp`（格式 `yyyy-MM-dd HH:mm:ss`）、`status`、`requestCount`
- 仅前端对外暴露（cpolar 穿透 5173），后端不对公网开放
## 版本信息
- Spring Boot: 2.7.x
- Java: 11+
- Vue: 3.x
- Vite: 5.x
## 许可
MIT 
