# 真实随机美国免税州地址生成器
[](LICENSE)
[]()
[]()
[]()
[]()
[]()
[]()
> 本仓库包含 MockAddress 的**开源前端核心引擎**，用于生成跨多个国家/地区的真实格式测试地址和 MAC 地址数据。
> 完整生产环境网站：
>
> 🇬🇧 **English users please see: [README_EN.md](./README_EN.md) (English Documentation)**
## 项目简介
MockAddress Core 是一个**纯前端、零后端依赖**的测试数据引擎，专为开发者和 QA 工程师设计，提供：
- **真实格式地址数据**，符合官方邮政标准（可在 Google Maps / Apple Maps 验证）
- 可选的**身份字段 + 信用卡字段**（仅用于表单/支付流程测试）
- **MAC 地址生成 + 厂商查询 + IPv6 Link-Local 推导**等网络测试数据
所有核心逻辑完全在浏览器端运行，可直接部署到任何静态托管环境（GitHub Pages、Cloudflare Pages、Vercel 等）。
> **注意**：本仓库仅开源**引擎和基础样式**。
> 大规模地址数据集和生产站点页面模板仍为 MockAddress 私有资产，用于在线服务。
---
## 主要特性
- **多国家/地区地址生成（引擎支持）**
- 支持为多个国家/地区生成符合本地邮政标准的地址结构
- 地址字段包含完整信息：街道、城市、州/省、邮编、国家等
- 可根据国家扩展本地化字段（如日本地址层级、香港中英文地址等）
- **真实格式 & 可验证**
- 地址数据基于官方邮政/统计数据 + OpenStreetMap 等公开数据源，经过清洗和整理
- 生成结果在设计上**可在 Google Maps / Apple Maps 等地图服务中验证**
- 适用于注册表单、支付页面、税费计算逻辑等对地址格式要求严格的场景
- **可选身份 & 信用卡字段（仅测试用）**
- 可选生成姓名、性别、生日、职业、本地化身份证号格式等
- 可选生成信用卡号（通过 Luhn 校验）、有效期、CVC 等字段
- 所有身份/卡片数据均为**随机生成，不对应任何真实个人或真实卡片**
- **批量导出 & 自动化友好**
- 内置 CSV / JSON 导出能力
- 适合自动化测试、回归测试、CI/CD 流水线批量注入测试数据
- **MAC 工具**
- 生成多种格式的 MAC 地址（冒号、短横、点、无分隔等）
- 基于 OUI 数据集进行厂商识别
- 支持从 MAC 推导 IPv6 Link-Local 地址
- 所有逻辑在浏览器本地完成，适用于网络测试、设备模拟、脚本开发
- **纯前端、隐私优先**
- 不依赖后端服务，全部逻辑在前端 JS 中完成
- 可选将生成结果保存到浏览器 `localStorage`，服务器不存储任何生成数据
---
## 仓库结构
```
mockaddress-core/
├── src/
│ ├── js/
│ │ ├── address-generator.js # 地址/身份/信用卡生成引擎
│ │ ├── mac-generator.js # MAC 生成与厂商查询
│ │ ├── storage.js # 存储、限流、导出工具
│ │ ├── language-switcher.js # 多语言路由与内部链接重写
│ │ ├── utils.js # 通用工具函数
│ │ └── config.js # 配置模块
│ └── css/
│ └── main.css # 通用暗色主题与基础 UI 组件样式
├── README.md # 项目文档（本文件）
├── README_EN.md # 英文文档
├── LICENSE # 开源协议（MIT）
├── CONTRIBUTING.md # 贡献指南
├── ROADMAP.md # 路线图
└── .gitignore # Git 忽略规则
```
> **提醒**：**本仓库不包含生产站点 HTML 文件和大规模数据文件 `data/*.json`**。
> 这些用于在线部署，不属于本次开源发布。
---
## 使用方式
### 快速开始
**方式一：直接使用（如果你的数据目录是 `data/`）**
```html
```
**方式二：自定义数据路径（推荐）**
```html
```
### 配置选项
- **`dataBasePath`**：你的数据文件基础路径（如 `'my-data/'`、`'/static/data/'`）
- **`autoDetectPaths`**：是否启用自动路径检测（默认 `true`，适合 mockaddress.com 的多语言结构）
> **重要**：如果你不调用 `configure()`，代码会使用默认行为，**完全不影响 mockaddress.com 的正常运行**。
### 可用函数
- `generateUSAddress(state)` - 美国地址
- `generateHKAddress(region, isEnglish)` - 香港地址
- `generateUKAddress(region)` - 英国地址
- `generateCAAddress(province)` - 加拿大地址
- `generateJPAddress(prefecture)` - 日本地址
- `generateINAddress(state)` - 印度地址
- `generateTWAddress(county)` - 台湾地址
- `generateSGAddress(state)` - 新加坡地址
- `generateDEAddress(state)` - 德国地址
- `generateTaxFreeAddress(state)` - 美国免税州地址
- `generateIdentityInfo(address)` - 身份信息
- `generateCreditCardInfo()` - 信用卡信息（测试用）
### 代码示例
**生成美国免税州地址：**
```javascript
import { generateTaxFreeAddress } from './src/js/address-generator.js';
// 生成俄勒冈州（免税州）地址
const address = await generateTaxFreeAddress('OR');
console.log(address);
// 输出: { street: "123 Main St", city: "Portland", state: "OR", zip: "97201", ... }
```
**生成地址 + 身份信息：**
```javascript
import { generateUSAddress, generateIdentityInfo } from './src/js/address-generator.js';
const address = await generateUSAddress('CA');
const identity = generateIdentityInfo(address);
console.log({ ...address, ...identity });
// 输出包含: name, gender, dateOfBirth, occupation, ssn 等
```
**生成 MAC 地址：**
```javascript
import { generateMACAddress, lookupVendor } from './src/js/mac-generator.js';
const mac = generateMACAddress('colon'); // 'aa:bb:cc:dd:ee:ff'
const vendor = await lookupVendor(mac);
console.log(vendor); // 来自 OUI 数据库的厂商信息
```
**导出为 CSV/JSON：**
```javascript
import { exportToCSV, exportToJSON, getAllSavedAddresses } from './src/js/storage.js';
// 保存一些地址后
const addresses = getAllSavedAddresses();
const csv = exportToCSV(addresses);
const json = exportToJSON(addresses);
// 下载或使用导出的数据
console.log(csv);
console.log(json);
```
### 在本机离线运行（仅自己使用，无需联网）
如果你和我一样，希望**只在自己的电脑上独享数据，不依赖任何外网服务器**，可以把整个 MockAddress Core 当成一个纯静态站点，在本机用一个简单的 HTTP 服务跑起来：
- 我的开发环境是 Windows 电脑，安装了：
- 一个现代浏览器（Chrome / Edge 等）
- Python / PHP / Node.js（至少其一，实际我三者都装了）
- 仓库代码放在本地某个目录，比如：`D:\mockaddress-core\`。
- 在项目根目录新建一个 `start-local-server.bat`，内容如下，一键启动本地服务器并自动打开浏览器访问 `http://localhost:8000`：
```bat
@echo off
echo Starting local server...
echo.
REM Check if Python 3 is available
python --version >nul 2>&1
if %errorlevel% equ 0 (
python -c "import sys; sys.exit(0 if sys.version_info >= (3, 0) else 1)" >nul 2>&1
if %errorlevel% equ 0 (
echo Found Python 3
echo Starting server on http://localhost:8000
echo Press Ctrl+C to stop
echo.
timeout /t 2 /nobreak >nul
start http://localhost:8000
python -m http.server 8000
exit /b 0
)
)
REM Check if Python 2 is available
python --version >nul 2>&1
if %errorlevel% equ 0 (
python -c "import sys; sys.exit(0 if sys.version_info < (3, 0) else 1)" >nul 2>&1
if %errorlevel% equ 0 (
echo Found Python 2
echo Starting server on http://localhost:8000
echo Press Ctrl+C to stop
echo.
timeout /t 2 /nobreak >nul
start http://localhost:8000
python -m SimpleHTTPServer 8000
exit /b 0
)
)
REM Check if PHP is available
php --version >nul 2>&1
if %errorlevel% equ 0 (
echo Found PHP
echo Starting server on http://localhost:8000
echo Press Ctrl+C to stop
echo.
timeout /t 2 /nobreak >nul
start http://localhost:8000
php -S localhost:8000
exit /b 0
)
REM Check if Node.js is available
where npx >nul 2>&1
if %errorlevel% equ 0 (
echo Found Node.js
echo Starting server on http://localhost:8000
echo Press Ctrl+C to stop
echo.
timeout /t 2 /nobreak >nul
start http://localhost:8000
npx --yes http-server -p 8000
exit /b 0
)
echo Error: No server found
echo Please install Python, PHP, or Node.js
pause
exit /b 1
```
运行方式：
- 双击 `start-local-server.bat`，脚本会依次尝试 Python 3 → Python 2 → PHP → Node.js，找到可用环境后自动启动本地服务器。
- 浏览器会自动打开 `http://localhost:8000`，此时**所有地址生成逻辑、包括美国地址生成器、香港中英文地址生成器等，全部只在你自己电脑本地运行，不依赖互联网**。
- 这种方式非常适合**内网环境**或对隐私/合规要求较高的团队。
详细使用说明请参考 [`使用说明.md`](./使用说明.md)。
你也可以参考我们的生产站点 查看真实使用场景和 UI 设计，然后在自己的项目中按需定制。
---
## 部署示例：Cloudflare & VPS（静态托管）
> 下列步骤是给要自己部署 mockaddress-core 的开发者看的，只描述最简单的路径，供 README 使用。
### 使用 Cloudflare Pages 部署（推荐给前端 / 无运维成本场景）
1. 在 GitHub 上创建仓库（例如 `mockaddress-core`），把本项目代码推送上去。
2. 登录 Cloudflare，进入 **Pages**，选择「使用 Git 提供商创建项目」，绑定这个仓库。
3. 构建设置：
- 框架预设：**None / 静态站点**
- 构建命令：留空（或 `npm run build`，如果你将来加了打包流程）
- 输出目录：设置为项目根目录（或者你的打包输出目录）
4. 部署后，确保：
- 所有 JS/CSS 通过 `