# 跨域调试

**Repository Path**: ck_px/cross-domain-debugging

## Basic Information

- **Project Name**: 跨域调试
- **Description**: HTML页面，快速测试你的 API 接口是否支持跨域请求（CORS），跨域 API 测试工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌐 跨域 API 测试工具

一个用于测试 API 接口是否支持跨域请求（CORS）的可视化工具，帮助开发者快速定位和解决跨域问题。

---

## 📋 功能特性

- ✅ **自定义请求**：支持 GET / POST / PUT / DELETE / PATCH 等各种 HTTP 方法
- ✅ **快捷测试**：一键测试常见跨域场景（简单请求、预检请求、携带凭证等）
- ✅ **详细分析**：展示请求/响应的完整信息，自动高亮 CORS 相关响应头
- ✅ **错误诊断**：请求失败时提供可能原因和解决建议
- ✅ **请求历史**：记录最近 20 次请求，方便对比测试
- ✅ **动态配置**：服务端支持通过 URL 参数动态控制 CORS 策略

---

## 🚀 快速开始

### 环境要求

- PHP 7.0+（需开启 `header()` 函数支持）
- PhpStudy 或其他支持 PHP 的 Web 服务器
- 现代浏览器（Chrome / Firefox / Edge）

### 部署步骤

1. 将整个项目目录放置到 Web 服务器的根目录下（如 PhpStudy 的 `WWW` 目录）
2. 确保目录结构如下：
   ```
   跨域测试/
   ├── index.html          # 前端测试页面
   ├── api/
   │   └── server.php      # 后端 API 接口
   └── README.md           # 本文档
   ```
3. 启动 Web 服务器
4. 在浏览器中访问 `http://localhost/跨域测试/index.html`

### 测试跨域

要真正测试跨域效果，需要从**不同域名**访问：

1. **同源访问**：直接在 `http://localhost/index.html` 页面测试
2. **跨域访问**：通过其他域名（如 `http://127.0.0.1/index.html` 或 `http://你的IP/index.html`）访问页面，然后请求 API

> 💡 `localhost` 和 `127.0.0.1` 在浏览器中属于**不同源**，可以用来模拟跨域场景。

---

## 📖 使用说明

### 基本用法

1. 在「API 地址」栏输入要测试的接口地址
2. 选择请求方法、Content-Type
3. 如有需要，填写请求体和自定义请求头
4. 点击「🚀 发送请求」查看结果

### 快捷测试场景

| 场景 | 说明 | 测试目的 |
|------|------|----------|
| ✅ 简单请求 | GET + text/plain | 测试最基本的跨域 |
| 🔄 预检请求 | POST + 自定义头 | 触发 OPTIONS 预检 |
| 📦 POST JSON | POST + JSON 数据 | 测试 JSON 跨域提交 |
| 🍪 携带凭证 | GET + credentials | 测试 Cookie 跨域传递 |
| 🚫 no-cors 模式 | POST + no-cors | 浏览器静默模式 |
| ✏️ PUT 请求 | PUT + JSON 数据 | 测试非简单方法跨域 |

### 对比测试

点击「🚫 无CORS头请求」按钮，会自动去掉 API 的 `origin` 参数，模拟服务端未配置 CORS 的情况，方便对比有无 CORS 头的差异。

---

## 🔧 API 接口说明

### 接口地址

```
api/server.php
```

### URL 参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `origin` | 允许的来源域名，`*` 表示允许所有 | `?origin=*` 或 `?origin=http://example.com` |
| `methods` | 允许的 HTTP 方法 | `?methods=GET,POST,PUT` |
| `headers` | 允许的自定义请求头 | `?headers=X-Custom-Header,Authorization` |
| `credentials` | 是否允许携带凭证 | `?credentials=true` |

> ⚠️ 不传任何参数时，API 不会返回任何 CORS 响应头，浏览器将阻止跨域访问。

### 响应格式

```json
{
    "success": true,
    "message": "跨域请求成功！",
    "method": "GET",
    "time": "2024-01-01 12:00:00",
    "received": {
        "headers": { ... },
        "get": { ... },
        "post": { ... }
    }
}
```

---

## 📚 跨域知识速查

### 什么是跨域？

浏览器的**同源策略**限制了一个源（协议 + 域名 + 端口）的网页向另一个源发送请求或读取响应。这是浏览器的重要安全机制。

### 什么是 CORS？

CORS（Cross-Origin Resource Sharing，跨源资源共享）是一种标准化的机制，允许服务端声明哪些外部源可以访问其资源，通过设置特定的 HTTP 响应头实现。

### 关键响应头

| 响应头 | 说明 |
|--------|------|
| `Access-Control-Allow-Origin` | 允许访问的源，`*` 或具体域名 |
| `Access-Control-Allow-Methods` | 允许的 HTTP 方法 |
| `Access-Control-Allow-Headers` | 允许的请求头 |
| `Access-Control-Allow-Credentials` | 是否允许携带 Cookie |
| `Access-Control-Max-Age` | 预检请求缓存时间（秒） |

### 简单请求 vs 预检请求

**简单请求**（不会触发预检）：
- 方法为 GET / POST / HEAD
- Content-Type 为 text/plain / multipart/form-data / application/x-www-form-urlencoded
- 不包含自定义请求头

**预检请求**（会先发送 OPTIONS 请求）：
- 使用 PUT / DELETE / PATCH 等方法
- Content-Type 为 application/json
- 包含自定义请求头（如 X-Custom-Header）

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 响应被拦截 | 缺少 `Access-Control-Allow-Origin` | 服务端添加该响应头 |
| OPTIONS 请求失败 | 服务端未处理预检请求 | 服务端对 OPTIONS 返回 204 |
| Cookie 无法传递 | 未设置 `Allow-Credentials` | 设置为 true，且 Origin 不为 * |
| 自定义头被拒绝 | 未在 `Allow-Headers` 中声明 | 添加对应的请求头名称 |

---

## 📁 项目结构

```
跨域测试/
├── index.html              # 前端测试页面（单文件，含 HTML/CSS/JS）
├── api/
│   └── server.php          # 后端 API 接口（支持动态 CORS 配置）
└── README.md               # 项目文档
```

---

## 📝 许可证

MIT License - 自由使用和修改。