archive/location-spoofer
1
0
Fork 0
mirror of https://github.com/xweiba/location-spoofer.git synced 2026-09-21 22:30:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh installation and feature previews

Browse Source
This commit is contained in:
xweiba
2026-08-07 16:45:02 +08:00
parent a3f39a93e7
commit c7ae14d4b2
8 changed files with 723 additions and 361 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.en.md
+334 -157
View File
@@ -2,216 +2,393 @@
# 📍 Location Spoofer # 📍 Location Spoofer
### iOS Location Spoofer · DingTalk · WeChat · Apple Watch Region Unlock · Fake GPS ### iOS Location Service Research & Testing Framework
**No jailbreak — rewrite Apple location-service responses through App Mode's on-device Wi-Fi HTTP proxy or Third-party Proxy Mode (Wi-Fi/4G/5G).**<br> An open-source project for **iOS location-service research, software development testing, and QA validation**.
Designed for DingTalk, WeChat, Apple Maps, and other apps that read system location. Map selection, favorites, mode setup, environment checks, and diagnostics live in one app.
The project uses either an on-device proxy or a third-party proxy client to simulate selected Apple location-service
responses in a controlled test environment.
[![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml) [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml) [![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod) [![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
[![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md) [![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
[![App Mode](https://img.shields.io/badge/App%20Mode-No%20VPN-16A34A)](#how-it-works)
[Features](#key-features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [中文](README.md) · [Changelog](docs/CHANGELOG.md) [Features](#feature-overview) ·
[How It Works](#how-it-works) ·
<img src="images/主界面.jpg" alt="Location Spoofer iOS Fake GPS main interface" width="380"> [Quick Start](#quick-start) ·
[Build](#building-the-project) ·
[中文](README.md)
</div> </div>
> [!IMPORTANT] > [!IMPORTANT]
> This project is only for education, security research, and testing on devices you own. App Mode requires a locally generated CA and a manual HTTP proxy on the current Wi-Fi network. In Third-party Proxy Mode, the selected client owns certificate, MITM, and proxy/VPN setup. Results vary by iOS version, network, location cache, and target-app behavior. Follow applicable laws, network policies, and service terms. > Use this project only for education, research, testing on devices you own, software development, and QA validation.
>
> Use it only on devices, networks, and software environments that you own or are authorized to test. Follow applicable
> laws, network policies, and service terms.
>
> The project does not guarantee compatibility with every iOS version or third-party app, and it does not promise to
> bypass third-party security controls, business restrictions, or service rules.
## Credits ## Project Scope
The core location-response rewriting approach and Go implementation are based on [Yu9191/wloc](https://github.com/Yu9191/wloc). This project adds a SwiftUI interface, MapKit selection, certificate and proxy guidance, environment verification, favorites, and diagnostics. Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.
## Why Location Spoofer? It provides:
Unlike tools that require a computer to stay connected, developer debugging, or a jailbroken device, Location Spoofer keeps selection and control on the iPhone. It provides two mutually exclusive paths: run the Go proxy inside the app, or synchronize coordinates to an existing third-party proxy client. - Native map selection and location-scenario switching;
- Controlled simulation of selected Apple location-service responses;
- App Mode and Third-party Proxy Mode;
- Map coordinate detection with paired WGS-84 and GCJ-02 values;
- Environment checks, runtime logs, and diagnostics;
- Favorite locations and restoration of the previous map state.
| Feature | Description | The project does not modify the target app's source code and does not provide telemetry, remote control, or data
collection services.
## Feature Overview
- **Native map interaction**
- Uses MapKit for the map and system blue dot;
- Supports search, map taps, center-point dragging, and zooming;
- Supports favorites and restoration of the latest selection;
- Shows both domestic and international coordinate representations with separate copy actions.
- **Location-service response simulation**
- Processes only the Apple location-service requests defined by the project;
- Returns the selected coordinates in a controlled test environment;
- Does not require changes to the target app.
- **Two runtime modes**
- App Mode: runs the Go proxy on-device and covers only the current Wi-Fi network;
- Third-party Proxy Mode: uses a supported proxy client and may cover Wi-Fi, 4G, or 5G depending on that client.
- **Environment checks**
- App Mode checks the local proxy, CA trust, and request path;
- Third-party Proxy Mode checks the WLOC configuration API and module response;
- Failures route to the relevant setup or diagnostics screen.
- **Development diagnostics**
- Runtime logs;
- Log copy and cleanup;
- Map coordinate-system change records;
- Sanitized issue-report generation.
## How It Works
### App Mode
App Mode runs the local Go proxy inside the app. A manual HTTP proxy on the current Wi-Fi routes the selected requests
through that on-device proxy.
```text
iOS location request
│
│ Manual HTTP proxy on the current Wi-Fi
▼
On-device wloccore Go proxy
│
│ Handle selected Apple location-service requests
▼
Apple location-service response
│
│ Test coordinate response
▼
The system and apps read the location result
```
App Mode:
- Does not create a Network Extension;
- Does not display or occupy the system VPN slot;
- Covers only the current Wi-Fi network;
- Requires a manual HTTP proxy on that Wi-Fi network;
- Requires installation and trust of the CA generated by the app;
- Handles only the Apple location-service and environment-verification traffic defined by the project. It is not a
general-purpose packet capture tool.
### Third-party Proxy Mode
Third-party Proxy Mode does not start the app's Go proxy and does not use the CA generated by the app.
```text
Map selection
│
│ WGS-84 coordinates
▼
WLOC configuration API
│
▼
Third-party proxy client stores the configuration
│
▼
Third-party client processes location-service requests
```
In this mode:
- The app owns map selection, favorites, coordinate synchronization, and coordinate clearing;
- The third-party client owns proxy/VPN, MITM, certificates, and rule execution;
- The third-party client owns coordinate persistence;
- Wi-Fi, 4G, and 5G support depends on the client;
- The configuration may remain active after Location Spoofer closes.
Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.
## Runtime Modes
### App Mode
Suitable for:
- Wi-Fi-only device testing;
- Local testing without a third-party proxy client;
- Workflows that need in-app proxy, certificate, and environment guidance.
Requirements:
- An iOS device;
- A Wi-Fi network that permits manual HTTP proxy configuration;
- Installation and trust of the local CA;
- Completion of the in-app proxy and environment checks.
### Third-party Proxy Mode
Suitable for:
- Tests that need Wi-Fi, 4G, or 5G coverage;
- Existing supported proxy-client workflows;
- Cases where the third-party client should keep the proxy configuration active.
Current client status:
| Client | Status |
|---|---| |---|---|
| 🔀 **Two runtime modes** | App Mode needs no third-party client and works over Wi-Fi; Third-party Proxy Mode can follow its client across Wi-Fi, 4G, and 5G. | | Shadowrocket | Currently used for on-device testing |
| 📱 **No jailbreak** | Can be installed through self-signing; minimum deployment target is iOS 15. | | Surge | Configuration provided, not fully verified |
| 🗺️ **Native Maps experience** | The same blue dot and selection gestures as Apple Maps — search, tap, and drag. | | Quantumult X | Configuration provided, not fully verified |
| 📍 **Location-response rewriting** | Can affect DingTalk, WeChat, Apple Maps, Amap, and other apps that read system location; verify compatibility on-device. | | Loon | Configuration provided, not fully verified |
| 🔍 **Visible map scale** | Left-side controls show the current visible range; place name adapts to zoom level. | | Stash | Configuration provided, not fully verified |
| 🧭 **Coordinate consistency** | Reconciles MapKit map coordinates with WGS-84 for favorites, restoration, and third-party sync. | | Egern | Uses the Surge module, not fully verified |
| 🧪 **Mode-aware checks** | App Mode checks the local proxy, CA trust, and Wi-Fi path; Third-party Mode verifies real module interception. |
| 🧾 **Diagnostics** | Search and copy logs, or generate a sanitized GitHub Issue report from inside the app. |
## Screenshots Module snapshots and provenance:
| Main Interface | Apple Maps | Amap | Apple Watch | - [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
|---|---|---|---| - [Yu9191/wloc](https://github.com/Yu9191/wloc)
| ![Location Spoofer main interface](images/主界面.jpg) | ![Apple Maps result](images/Apple%20Map.jpg) | ![Amap result](images/高德地图.jpg) | ![Apple Watch region feature](images/高血压.jpg) |
## Key Features The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and
scripts before importing them.
- **iOS Location Spoofer / Fake GPS**: Apply the selected pin to App Mode's proxy or synchronize it to a third-party WLOC module.
- **Native map and real-time location**: Uses MapKit's blue dot with search, tap, map-center drag, zoom controls, and a shortcut to Apple Maps.
- **Concurrency-safe selection**: Pan, tap, search, favorites, and async location respect the user's latest intent; stale results won't overwrite newer selections.
- **Hierarchical place names**: POI, street, or road at close zoom; neighborhood, district, city, or province at wider zoom.
- **Map scale display**: Zoom controls show the current visible range.
- **Favorites and state restoration**: Save, rename, and switch frequent locations while remembering the last pin and map range.
- **Automatic coordinate handling**: Resolves the map's coordinate convention at startup and keeps paired WGS-84/map coordinates to reduce mainland-China map offsets.
- **Mode-specific onboarding**: App Mode guides local proxy and CA setup; Third-party Mode guides client selection, subscription import, and connection testing.
- **Local-proxy keep-alive**: App Mode uses silent audio while spoofing to remain active in the background and rechecks the environment after Wi-Fi changes.
- **Structured diagnostics**: Logs rotate automatically, retain only three days, and can be filtered, copied, cleared, or attached to an Issue report.
- **Third-party Proxy Mode (testing)**: Query, save, or clear WGS-84 coordinates through a WLOC module. The proxy client persists state, so spoofing may continue after this app closes.
## Quick Start ## Quick Start
### 1. Install the App ### 1. Install the App
Release assets are unsigned IPA files and must be installed with a sideloading tool: You can use:
1. **Enable sideloading support**: On iOS 16 or later, open Settings → Privacy & Security → Developer Mode, enable it, then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step there. - Your own Apple Developer signing environment;
2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download the latest `PaopaoLocationSpoofer-unsigned.ipa`. - A self-signing tool suitable for personal testing;
3. **Prepare a sideloading tool**: Download the appropriate Impact build from [Impact Releases](https://github.com/claration/Impactor/releases/latest). Aisi Assistant/i4Tools or another tool that supports signing and installing IPA files may also be used. - The unsigned IPA published in Releases;
4. **Connect and install**: Connect the iPhone to the computer with a USB cable, tap “Trust This Computer” on the phone, select the downloaded IPA in the sideloading tool, and follow that tool's prompts to sign and install it. - A source build produced on macOS using the [build guide](docs/BUILD.md).
> Impact supports Windows, macOS, and Linux. If Windows cannot detect the device, install iTunes to provide the Apple device drivers. Aisi Assistant/i4Tools is third-party software; download it only from its official source and assess its account, certificate, and privacy risks yourself. Free self-signing environments may not provide Network Extension capabilities. App Mode therefore uses an on-device
proxy plus a manual Wi-Fi HTTP proxy and does not depend on a VPN component.
If iOS blocks the installed app, trust its developer app under Settings → General → VPN & Device Management. A free Apple ID signature normally expires after seven days and must then be renewed; this is separate from the WLOC CA certificate. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged. #### Self-Signing Instructions
To build the unsigned IPA yourself on macOS with Xcode, follow the [build guide](docs/BUILD.md), then use the same sideloading steps above to sign and install it. Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:
### 2. Choose a Runtime Mode 1. **Enable sideloading support**: On iOS 16 or newer, open Settings → Privacy & Security → Developer Mode, enable it,
then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step.
2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download
the latest `PaopaoLocationSpoofer-unsigned.ipa`.
3. **Prepare signing software**: Download the appropriate Impactor build from
[Impactor Releases](https://github.com/claration/Impactor/releases). Other tools that support self-signing and installing
IPA files, such as Aisi Assistant, may also be used.
4. **Connect and install**: Connect the iPhone to the computer with a USB cable, choose “Trust This Computer” on the
phone, select the downloaded IPA in the signing software, and follow that tool's instructions to sign and install it.
#### App Mode (On-device Wi-Fi) Impactor supports Windows, macOS, and Linux. If Windows cannot detect the device, install the Apple device drivers supplied
with iTunes first. Aisi Assistant is third-party software; obtain it from its official channel and evaluate its account,
certificate, and privacy risks yourself.
Choose App Mode during first launch, then follow the in-app guide to configure the proxy and CA. This mode starts `wloccore` on the device and has no third-party client dependency, but its traffic entry point covers only the current Wi-Fi. After installation, if iOS blocks the app from opening, go to Settings → General → VPN & Device Management and trust the
corresponding developer app. A free Apple ID signature normally expires after seven days and must then be renewed.
On the current Wi-Fi network, set Configure Proxy to Manual: ### 2. First Launch
1. Choose App Mode or Third-party Proxy Mode;
2. Complete the corresponding in-app setup;
3. Run the environment check;
4. Search, tap, or drag on the map to select a test location;
5. Enable the test location and verify the result in the authorized test environment.
### 3. Restore the Real Location
App Mode:
1. Stop the test location;
2. Disable the manual HTTP proxy on the current Wi-Fi network;
3. Follow the in-app instructions to refresh the location environment.
Third-party Proxy Mode:
1. Clear the WLOC coordinates from the app;
2. Disable the corresponding module or proxy in the third-party client;
3. Restore HTTPS decryption and proxy settings according to the client documentation.
Location caches may take time to refresh. Restart the device if the system or target app continues to show an old
location.
## Coordinate Handling
The project stores two coordinate representations:
- WGS-84: the international standard used for WLOC writes;
- GCJ-02: the domestic map representation used where required.
MapKit does not expose a public API that reports whether its current runtime output uses GCJ-02 or WGS-84. The project
uses a fixed-anchor query to resolve the active representation and performs controlled refreshes after blue-dot changes
and explicit user actions.
Each write boundary stores a complete WGS-84/GCJ-02 pair. Rendering selects the field matching the confirmed map
representation instead of repeatedly converting an already typed value.
## Project Structure
```text ```text
Server: 127.0.0.1 App/ SwiftUI interface, MapKit, location, and runtime flow
Port: 8888 Core/ Go proxy, certificate server, and location-response handling
Authentication: off Shared/ Coordinates, favorites, logs, configuration, and shared models
Resources/ Info.plist, Entitlements, and resources
Config/ Build configuration
Scripts/ Build, packaging, and validation scripts
Tests/ XCTest and Shell contract tests
docs/ Build, module, and release documentation
``` ```
Return to the app and run the environment check. If the CA is not trusted, the app opens the complete certificate setup flow. Download the profile, then: ## Building the Project
```text Source builds require:
Settings → General → VPN & Device Management → install WLOC CA
Settings → General → About → Certificate Trust Settings → enable full trust
```
#### Third-party Proxy Mode (Testing) - macOS;
- Xcode;
- Xcode Command Line Tools;
- XcodeGen;
- Go 1.23 or newer.
The app handles map selection, favorites, and querying, saving, or clearing WGS-84 coordinates. A third-party proxy client handles WLOC interception, MITM, and persistence. This mode does not start the local Go proxy, use the app-generated CA, or require `127.0.0.1:8888`. Network coverage depends on the selected client and may include Wi-Fi, 4G, and 5G. Building the iOS app directly on Windows is not supported.
Select a client during onboarding or from Settings → Runtime Mode. The app can copy the official subscription URL and open the selected client; paste that URL into its module, rewrite, or override subscription UI.
| Client | Verification status | Configuration |
|---|---|---|
| Shadowrocket | **Currently available for testing** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
| Surge | Provided, not verified | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
| Quantumult X | Provided, not verified | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
| Loon | Provided, not verified | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
| Stash | Provided, not verified | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
| Egern | Provided, not verified | Uses the Surge module |
For Shadowrocket, also enable HTTPS decryption for `gs-loc.apple.com`. Import `.stoverride` directly into Stash without Script Hub conversion; Egern reuses the Surge module. The client—not this app—owns module enablement, MITM, certificates, and proxy/VPN state. A connection test passes only when the endpoint returns valid module JSON, not merely HTTP 200. Bundled snapshots and provenance are documented in [Third-party Module Snapshots](docs/THIRD_PARTY_MODULES.md).
### 3. Select a Location & Enable
1. Search, tap, or drag the map to pick a location; use the location button to return to the MapKit blue dot, or save the pin as a favorite.
2. In App Mode, tap “Start Spoofing” and wait for verification. In Third-party Proxy Mode, tap “Sync to Third-party Proxy.”
3. Follow the in‑app activation instructions to refresh airplane mode, Wi‑Fi, and location services.
4. Open Apple Maps or your target app to verify.
### 4. Restore Your Real Location
In App Mode, stop spoofing and disable the current Wi-Fi's manual proxy. In Third-party Mode, use “Clear Third-party Proxy Coordinates,” then disable the module or proxy connection if needed. Follow the in-app deactivation instructions to refresh the system location cache; restart the device if the old location remains.
## How It Works
### Why App Mode Needs No VPN
```text
iPhone location request
│ Wi‑Fi HTTP proxy: 127.0.0.1:8888
▼
Local wloccore Go proxy
│ Handles only the targeted Apple location-service traffic
▼
Apple location service response
│ The selected coordinate is written into the response
▼
The system and applications receive the modified result
```
App Mode does not create a Network Extension tunnel, so it does not display or occupy a VPN connection. **It still requires the current Wi-Fi's manual HTTP proxy and a fully trusted local CA.**
### Third-party Proxy Mode
```text
Map pin (WGS-84) → WLOC settings endpoint → proxy module stores coordinate
│
Location request → third-party proxy/VPN + MITM ┘→ rewritten response
```
The selected client owns proxy/VPN, certificates, and MITM and may cover cellular networks. Do not enable both interception paths at once.
## Data & Security Notes
- App Mode generates its CA and private key on-device. The private key is stored in the iOS Keychain; only the CA profile is installed into the system trust store.
- Third-party modules and runtime scripts come from the upstream project. Review them before importing. Bundled snapshots provide release provenance and do not imply that every client has been verified.
- Runtime logs live in the App Group container, rotate automatically, and retain only three days. They can be copied or cleared in-app. Exportable real-time-location diagnostics omit exact coordinates by default.
- A self-signed CA or third-party MITM changes the device's HTTPS trust/proxy path. Disable the proxy or module when unused and remove certificates if appropriate.
## Compatibility
| Item | Requirement |
|---|---|
| iOS | 15.0+ |
| Build | macOS, Xcode, XcodeGen |
| Swift | 5.9 |
| Go | 1.23+ |
| Network | App Mode: Wi-Fi with manual HTTP proxy support; Third-party Mode (testing): client-dependent Wi-Fi/4G/5G |
| Installation | Self-sign or use release builds |
Actual behavior may vary with iOS version, network conditions, system location cache, device model, and the target app's own location strategy. Compatibility with every iOS version or third-party app is not guaranteed.
## Build & Project Structure
Building requires macOS, Xcode Command Line Tools, Go 1.23+, and XcodeGen:
```bash ```bash
./build.sh # build the unsigned IPA git clone https://github.com/xweiba/location-spoofer.git
./build.sh --test # also run iOS Simulator unit tests cd location-spoofer
./build.sh
``` ```
The unsigned IPA is at: Build and run Simulator tests:
```bash
./build.sh --test
```
The build script generates an unsigned IPA:
```text ```text
dist/PaopaoLocationSpoofer-unsigned.ipa dist/PaopaoLocationSpoofer-unsigned.ipa
``` ```
```text Deploy it to a test device using your own signing and installation process.
App/ SwiftUI, MapKit, location and setup flow
Core/ Go local proxy and location response rewriting
Shared/ Favorites, settings, logs, and shared models
Resources/ Info.plist, Entitlements, and icons
Config/ Build configuration
Scripts/ Build, signing, and verification scripts
Tests/ XCTest and Bash contract tests
docs/ Build, third-party module, and release documentation
```
## Documentation & Feedback ## Privacy and Security Boundaries
- The project contains no telemetry or remote-control service;
- The project does not automatically upload location data;
- Runtime logs remain in the device App Group container and retain only the latest three days;
- Issue reports are copied by the user before being submitted to GitHub;
- App Mode accesses the local proxy and the environment-verification URL;
- Third-party Proxy Mode may access the upstream module URL and the WLOC configuration endpoint;
- The CA private key generated by the app is stored in the device Keychain;
- Third-party MITM, certificates, and proxy behavior are owned by the selected client.
Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.
## Limitations
- iOS updates may change location-service behavior;
- MapKit coordinate output can vary with the system, region, and location environment;
- System location caches may delay visible changes;
- Each third-party proxy client requires separate compatibility testing;
- Not every app uses the same location API;
- Not every app or service accepts test coordinates;
- Behavior is not guaranteed across every network, device model, or iOS version.
## Contributing
Contributions are welcome for:
- Bug reports;
- Feature requests;
- Compatibility results;
- Performance improvements;
- Documentation improvements;
- Additional tests.
When filing an issue, include:
- iOS version;
- Device model;
- Runtime mode;
- Reproduction steps;
- Sanitized runtime logs;
- Whether a third-party proxy client was used.
## Documentation
- [Build guide](docs/BUILD.md) - [Build guide](docs/BUILD.md)
- [Third-party module snapshots](docs/THIRD_PARTY_MODULES.md) - [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
- [Changelog](docs/CHANGELOG.md) - [Changelog](docs/CHANGELOG.md)
- [中文文档](README.md) - [中文文档](README.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues) - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
When reporting issues, please include reproduction steps, iOS version, device model, and sanitized runtime logs. ## Feature Preview
## Links These screenshots show the main interface and selected on-device test scenarios. Actual results depend on the iOS
version, network environment, system caches, and the target app's location strategy; they are not a compatibility
guarantee for every app or release.
**LinuxDo** — [https://linux.do](https://linux.do/) <table>
<tr>
<th>Main interface</th>
<th>Apple Maps test</th>
<th>Amap test</th>
</tr>
<tr>
<td><img src="images/主界面.jpg" alt="Location Spoofer map selection interface" width="220"></td>
<td><img src="images/Apple%20Map.jpg" alt="Apple Maps location test scenario" width="220"></td>
<td><img src="images/高德地图.jpg" alt="Amap location test scenario" width="220"></td>
</tr>
<tr>
<th>WeChat test</th>
<th>DingTalk test</th>
<th>Apple Watch scenario test</th>
</tr>
<tr>
<td><img src="images/微信.jpg" alt="WeChat location test scenario" width="220"></td>
<td><img src="images/钉钉.jpg" alt="DingTalk location test scenario" width="220"></td>
<td><img src="images/高血压.jpg" alt="Apple Watch region-feature test scenario" width="220"></td>
</tr>
</table>
## Acknowledgements and Links
The core location-response handling approach, Go implementation, and third-party modules are based on:
- [Yu9191/wloc](https://github.com/Yu9191/wloc)
Community link:
- [LINUX DO](https://linux.do/)
Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
tools.
README.md
+319 -196
View File
@@ -2,261 +2,384 @@
# 📍 Location Spoofer # 📍 Location Spoofer
### iOS 虚拟定位 · 钉钉定位 · 微信定位 · Apple Watch 国区功能解锁 · Fake GPS ### iOS Location Service Research & Testing Framework
**无需越狱；通过 APP 模式的本机 Wi‑Fi HTTP 代理，或第三方代理模式（Wi‑Fi/4G/5G）改写 Apple 定位服务响应。**<br> 一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
适用于钉钉、微信、Apple 地图等读取系统定位的 App。地图选点、收藏、模式配置、环境检测和问题诊断集中在一个 App 中。
项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
不同地理位置和定位场景下的行为。
[![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml) [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml) [![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod) [![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
[![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md) [![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
[![App Mode](https://img.shields.io/badge/APP模式-无需VPN-16A34A)](#工作原理)
[功能介绍](#核心功能) · [快速开始](#快速开始) · [工作原理](#工作原理) · [English](README.en.md) · [更新日志](docs/CHANGELOG.md) [功能概览](#功能概览) ·
[工作原理](#工作原理) ·
<img src="images/主界面.jpg" alt="Location Spoofer iOS 虚拟定位 Fake GPS 主界面" width="380"> [快速开始](#快速开始) ·
[构建项目](#构建项目) ·
[English](README.en.md)
</div> </div>
> [!IMPORTANT] > [!IMPORTANT]
> 本项目仅用于学习、安全研究和自有设备测试。APP 模式需要安装本机生成的 CA，并为当前 Wi‑Fi 配置 HTTP 代理；第三方代理模式的证书、MITM 及代理/VPN 连接由所选客户端负责。实际效果受 iOS、网络、定位缓存和目标 App 策略影响，请遵守当地法律、网络管理规则及相关服务条款。 > 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
>
> 请仅在你拥有或获得授权的设备、网络和软件环境中使用，并遵守当地法律法规、网络管理规定以及相关服务条
> 款。
>
> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。
## 致谢 ## 项目定位
核心定位响应改写思路与 Go 实现来源于 [Yu9191/wloc](https://github.com/Yu9191/wloc)。本项目在此基础上增加 SwiftUI 界面、MapKit 选点、证书与代理引导、环境验证、收藏和诊断能力。 Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。
## 为什么选择 Location Spoofer？ 它提供：
很多 iOS 虚拟定位工具依赖电脑常驻、开发者调试或越狱。本项目把选点和控制流程放在 iPhone 上，并提供两条互斥的运行路径：由 App 在本机启动 Go 代理，或把坐标同步给已有的第三方代理客户端。 - 原生地图选点和位置场景切换；
- Apple 定位服务响应的测试环境模拟；
- 本地代理和第三方代理两种运行模式；
- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
- 环境检测、运行日志和问题诊断；
- 收藏位置和上次地图状态恢复。
| 特性 | 说明 | 项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
|---|---|
| 🔀 **双运行模式** | APP 模式无需第三方客户端、适用于 Wi‑Fi；第三方代理模式可随客户端覆盖 Wi‑Fi、4G 和 5G |
| 📱 **无需越狱** | 支持自行签名安装，最低部署目标为 iOS 15 |
| 🗺️ **原生地图体验** | 使用 Apple 地图同款蓝点，搜索、点击、拖动选点体验与 Apple 地图一致 |
| 📍 **系统定位响应改写** | 可影响钉钉、微信、Apple 地图、高德等读取系统定位的 App，兼容性以真机结果为准 |
| 🔍 **可见缩放范围** | 左侧缩放控件显示当前可视范围，地点名称随级别自动适配 |
| 🧭 **坐标一致性** | 自动处理 MapKit 地图坐标与 WGS-84，收藏、恢复和第三方同步使用明确的坐标来源 |
| 🧪 **按模式检测** | APP 模式检查本地代理、CA 信任和 Wi‑Fi 链路；第三方模式验证模块是否真正拦截请求 |
| 🧾 **问题诊断** | 日志可搜索、逐条或整体复制，并可生成已脱敏的 GitHub Issue 报告 |
## 效果预览 ## 功能概览
<table> - **原生地图交互**
<tr> - 使用 MapKit 显示地图和系统蓝点；
<th>应用主界面</th> - 支持搜索、点击选点、拖动地图中心和缩放；
<th>钉钉</th> - 支持收藏位置和恢复上次选点；
<th>微信</th> - 当前选点同时显示国内坐标和国际坐标，可分别复制。
</tr>
<tr>
<td><img src="images/主界面.jpg" alt="iOS 虚拟定位应用主界面" width="180"></td>
<td><img src="images/钉钉.jpg" alt="钉钉虚拟定位打卡" width="180"></td>
<td><img src="images/微信.jpg" alt="微信虚拟定位" width="180"></td>
</tr>
<tr>
<th>Apple 地图</th>
<th>高德地图</th>
<th>Apple Watch</th>
</tr>
<tr>
<td><img src="images/Apple%20Map.jpg" alt="Apple Maps 定位效果" width="180"></td>
<td><img src="images/高德地图.jpg" alt="高德地图定位效果" width="180"></td>
<td><img src="images/高血压.jpg" alt="Apple Watch 地区功能验证" width="180"></td>
</tr>
</table>
## 核心功能 - **定位服务响应模拟**
- 通过代理层处理指定的 Apple 定位服务请求；
- 在测试环境中返回选定的坐标数据；
- 不需要修改目标 App 代码。
- **iOS 虚拟定位 / Fake GPS**：将当前选点写入 APP 模式代理，或同步给第三方 WLOC 模块。 - **双运行模式**
- **原生地图与实时位置**：使用 MapKit 蓝点，支持搜索、点击、拖动地图中心、缩放以及快速打开 Apple 地图。 - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
- **并发安全选点**：拖动、点击、搜索、收藏和异步定位按用户最新意图处理，旧结果不会覆盖新选点。 - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
- **地点名称分级**：近距离显示 POI、门牌或道路；拉远后显示社区、区县、城市或省份。
- **地图范围显示**：缩放控件中显示 `180 m`、`2.5 km`、`126 km` 等当前可视范围。
- **收藏与状态恢复**：保存、重命名和切换常用位置，记住最后图钉与地图范围。
- **坐标系自动处理**：启动时确认地图坐标标准，内部保留 WGS-84 与地图坐标配对，减少中国大陆地图偏移。
- **分模式首次引导**：APP 模式配置本机代理和 CA；第三方模式选择客户端、复制订阅地址并检测连接。
- **本机代理保活**：APP 模式启动虚拟定位后使用静音音频维持后台运行，并响应网络切换重新检测环境。
- **结构化诊断**：运行日志自动轮转，仅保留近 3 天；支持过滤、复制、清空和生成 Issue 报告。
- **第三方代理模式（测试）**：向模块查询、保存或清除 WGS-84 坐标；坐标由代理客户端持久化，关闭本 App 后仍可能继续生效。
## 快速开始 - **环境检测**
- APP 模式检测本地代理、证书信任和请求链路；
- 第三方代理模式检测 WLOC 配置接口和模块响应；
- 失败时提供对应的配置或诊断入口。
### 1. 安装 App - **开发调试**
- 运行日志；
#### 自签安装 - 日志复制和清理；
- 坐标标准变化记录；
Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone： - 脱敏问题报告生成。
1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并确认；iOS 15 没有此开关，可跳过本步。
2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的 `PaopaoLocationSpoofer-unsigned.ipa`。
3. **准备自签软件**：前往 [Impact Releases](https://github.com/claration/Impactor/releases/latest) 下载对应系统版本的 Impact；也可以使用爱思助手等支持 IPA 自签安装的软件。
4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择刚下载的 IPA，根据软件提示完成签名与安装。
> Impact 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供 Apple 设备驱动。爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费 Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
本项目自身不包含 VPN、Network Extension 或 Packet Tunnel Provider，但签名工具仍需保留 App 的标识和声明能力。
需要自行构建时执行：
```bash
./build.sh
```
输出文件为 `dist/PaopaoLocationSpoofer-unsigned.ipa`，随后按上面的自签步骤安装到设备。完整构建要求见[构建说明](docs/BUILD.md)。
签名时不要修改以下标识，也不要移除 App Group 和 Wi-Fi 信息能力：
| 组件 | 标识 |
|---|---|
| 主 App Bundle ID | `com.paopaolabs.location-spoofer` |
签名有效期是 Apple 的侧载限制，不是 WLOC CA 失效。CA 私钥保存在 iOS 钥匙串中：相同 Bundle ID 和钥匙串访问范围下重装通常可以复用，但卸载、系统清理或签名能力变化后不保证保留。
### 2. 选择运行模式
#### APP 模式（本机 Wi‑Fi）
首次打开后选择 APP 模式，再按 App 内引导配置代理和 CA。此模式会在设备内启动 `wloccore`，不依赖第三方代理客户端，但流量入口只覆盖当前 Wi‑Fi。
##### 配置当前 Wi‑Fi 代理
首次打开后，先在当前 Wi‑Fi 的“配置代理”中选择“手动”：
```text
服务器：127.0.0.1
端口：8888
鉴定：关闭
```
返回 App 后运行环境检测；若设备尚未信任 CA，App 会进入完整的证书初始化流程。
##### 安装并信任 CA
按首次引导下载描述文件，然后依次完成：
```text
设置 → 通用 → VPN 与设备管理 → 安装 WLOC CA
设置 → 通用 → 关于本机 → 证书信任设置 → 完全信任
```
#### 第三方代理模式（测试）
此模式由 App 负责地图选点、收藏以及查询、同步和清除 WGS-84 坐标；WLOC 拦截、MITM 与坐标持久化由第三方代理客户端负责。它不会启动本机 Go 代理，不使用 App 生成的 CA，也不要求配置 `127.0.0.1:8888`。网络覆盖范围取决于代理客户端，可包括 Wi‑Fi、4G 和 5G。
首次引导或“设置 → 运行模式”切换后，选择客户端。App 提供官方订阅地址复制和客户端跳转按钮；在对应客户端的模块、重写或覆写订阅入口粘贴地址并导入。仓库和 App 包内仍保留以下模块配置快照，用于版本归档和离线核对：
| 客户端 | 状态 | 模块 |
|---|---|---|
| Shadowrocket（小火箭） | **当前可测试** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
| Surge | 配置已提供，尚未验证 | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
| Quantumult X | 配置已提供，尚未验证 | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
| Loon | 配置已提供，尚未验证 | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
| Stash | 配置已提供，尚未验证 | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
| Egern | 配置已提供，尚未验证 | 直接使用 Surge 模块 |
Shadowrocket 还需为 `gs-loc.apple.com` 开启 HTTPS 解密。Stash 应直接订阅 `.stoverride`，无需通过 Script Hub 转换；Egern 复用 Surge 配置。导入后仍需按客户端自己的流程启用模块、MITM、证书和代理/VPN 连接，这些状态不由本 App 管理。“检测连接”只有在接口返回有效模块 JSON 时才会通过，普通 HTTP 200 不会被误判为成功。
> 第三方代理模式目前是测试模式。内置模块快照来源及版本记录见 [第三方模块说明](docs/THIRD_PARTY_MODULES.md)；模块引用的运行脚本仍由第三方客户端按配置访问。上游更新可能改变行为；当前仅计划使用 Shadowrocket 做真机验证。
### 3. 选点并启用
1. 搜索、点击或拖动地图选择位置；点击定位按钮可回到当前 MapKit 蓝点，也可以保存为收藏。
2. APP 模式点击“开始虚拟定位”并等待环境检测；第三方代理模式点击“同步到第三方代理”。
3. 按 App 内“生效说明”刷新飞行模式、Wi‑Fi 和定位服务状态。
4. 打开 Apple 地图或目标 App 验证结果。
### 4. 恢复真实位置
APP 模式下先停止虚拟定位，再关闭当前 Wi‑Fi 的手动代理；第三方代理模式下使用“清除第三方代理坐标”，必要时再停用对应模块或代理连接。随后按 App 内“失效说明”刷新系统定位缓存；若仍保留旧位置，请重启设备后再检查。
## 工作原理 ## 工作原理
### APP 模式为什么不需要 VPN？ ### APP 模式
APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
```text ```text
iPhone 定位请求 iOS 定位请求
│ 当前 Wi‑Fi HTTP 代理：127.0.0.1:8888 │
│ 当前 Wi-Fi 手动 HTTP 代理
▼ ▼
本机 wloccore（Go） 设备内 wloccore Go 代理
│ 仅处理目标 Apple 定位服务请求 │
├──────────────► Apple 定位服务 │ 处理指定 Apple 定位服务请求
◄──────────────┘
│ 改写目标响应中的坐标
▼ ▼
系统与应用读取定位结果 Apple 定位服务响应
│
│ 测试坐标响应
▼
系统和应用读取定位结果
``` ```
APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN 连接，也不会占用系统 VPN。**它仍然需要当前 Wi‑Fi 的手动 HTTP 代理以及已完全信任的本机 CA。** APP 模式：
- 不创建 Network Extension；
- 不显示或占用系统 VPN；
- 只覆盖当前 Wi-Fi 网络；
- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
- 需要安装并信任 App 生成的本机 CA；
- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
### 第三方代理模式 ### 第三方代理模式
第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
```text ```text
地图选点（WGS-84） → WLOC 配置接口 → 第三方代理模块保存坐标 地图选点
│ │
系统定位请求 → 第三方客户端代理/VPN + MITM ─┘→ 改写定位响应 │ WGS-84 坐标
▼
WLOC 配置接口
│
▼
第三方代理客户端保存配置
│
▼
第三方代理客户端处理定位服务请求
``` ```
第三方模式由所选客户端管理代理/VPN、证书和 MITM，可覆盖蜂窝网络。两种模式不要同时拦截 WLOC 请求。 在该模式下：
## 数据与安全说明 - App 负责地图选点、收藏、坐标同步和清除；
- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
- 坐标持久化由第三方客户端负责；
- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
- App 关闭后，第三方客户端中的配置可能继续生效。
- APP 模式的 CA 和私钥在设备本地生成，私钥存入 iOS 钥匙串；安装到系统的是 CA 描述文件。 不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
- 第三方代理模块及运行脚本来自上游项目，导入前请自行检查；仓库内快照用于版本留档，不代表已验证所有客户端。
- 运行日志位于 App Group 容器，自动轮转并仅保留近 3 天；可在 App 内复制或清空。可导出的实时定位诊断默认不记录精确坐标。
- 使用自签 CA 或第三方 MITM 都会改变设备的 HTTPS 信任/代理链路；不用时应关闭代理或模块，并按需移除证书。
## 兼容性 ## 运行模式
| 项目 | 要求 | ### APP 模式
适用于：
- 只使用 Wi-Fi 的设备测试；
- 不依赖第三方代理客户端的本地验证；
- 需要在 App 内完成代理、证书和环境检测的场景。
使用条件：
- iOS 设备；
- 当前 Wi-Fi 支持手动 HTTP 代理；
- 安装并信任本机 CA；
- 在 App 内完成代理配置和环境检测。
### 第三方代理模式
适用于：
- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
- 已经使用支持模块或脚本的代理客户端；
- 希望由第三方客户端继续保持代理配置的场景。
当前客户端状态：
| 客户端 | 状态 |
|---|---| |---|---|
| iOS | 15.0+ | | Shadowrocket | 当前用于真机测试 |
| 构建 | macOS、Xcode、XcodeGen | | Surge | 已提供配置，尚未完整验证 |
| Swift | 5.9 | | Quantumult X | 已提供配置，尚未完整验证 |
| Go | 1.23+ | | Loon | 已提供配置，尚未完整验证 |
| 网络 | APP 模式：可手动配置 HTTP 代理的 Wi‑Fi；第三方代理模式（测试）：取决于客户端，可覆盖 Wi‑Fi/4G/5G | | Stash | 已提供配置，尚未完整验证 |
| 安装 | 自行签名或使用 Releases 构建产物 | | Egern | 使用 Surge 模块，尚未完整验证 |
效果会受到 iOS 版本、网络、系统定位缓存和目标 App 自身策略影响，不承诺兼容所有系统或第三方 App。 相关模块快照和来源记录：
## 构建与项目结构 - [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
- [Yu9191/wloc](https://github.com/Yu9191/wloc)
构建要求为 macOS、Xcode Command Line Tools、Go 1.23+ 和 XcodeGen。执行： 第三方客户端、证书、MITM 和代理开关由客户端自身负责。导入任何第三方模块前，请先审查其配置和脚本内容。
## 快速开始
### 1. 安装应用
你可以使用：
- 自己的 Apple Developer 签名环境；
- 适合个人测试的自签工具；
- 项目 Releases 中的未签名 IPA；
- 在 macOS 上按[构建说明](docs/BUILD.md)自行构建。
免费自签环境可能无法使用 Network Extension，因此 APP 模式采用设备内本地代理和 Wi-Fi 手动代理，不依赖
VPN 组件。
#### 自签安装说明
Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并
确认；iOS 15 没有此开关，可跳过本步。
2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的
`PaopaoLocationSpoofer-unsigned.ipa`。
3. **准备自签软件**：前往 [Impactor Releases](https://github.com/claration/Impactor/releases) 下载对应系统
版本的 Impactor；也可以使用爱思助手等支持 IPA 自签安装的软件。
4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择
刚下载的 IPA，根据软件提示完成签名与安装。
Impactor 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供的 Apple 设备驱动。
爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费
Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
### 2. 首次启动
首次启动时：
1. 选择 APP 模式或第三方代理模式；
2. 按照 App 内引导完成对应配置；
3. 执行环境检测；
4. 在地图中搜索、点击或拖动选择测试位置；
5. 启用测试位置并在目标测试环境中验证结果。
### 3. 恢复真实位置
APP 模式：
1. 停止测试位置；
2. 关闭当前 Wi-Fi 的手动 HTTP 代理；
3. 按 App 内提示刷新定位环境。
第三方代理模式：
1. 使用 App 清除 WLOC 坐标；
2. 在第三方客户端中关闭对应模块或代理；
3. 按客户端要求恢复 HTTPS 解密和代理设置。
如果系统或目标应用仍显示旧位置，可能需要等待定位缓存刷新，必要时重启设备后再次验证。
## 坐标处理
项目内部保存两种坐标表示：
- WGS-84：国际标准，WLOC 写入使用此坐标；
- GCJ-02：国内地图标准，用于需要国内地图坐标的场景。
MapKit 不提供公开 API 直接返回当前是否使用 GCJ-02 或 WGS-84。项目通过固定锚点查询判断 MapKit 当前返回
标准，并在运行期间根据蓝点变化和用户操作进行受控刷新。
坐标写入边界会保存完整的 WGS-84 / GCJ-02 坐标对，使用时根据当前地图标准选择对应字段，避免重复转换造成
位置偏移。
## 项目结构
```text
App/ SwiftUI 界面、MapKit、定位和运行流程
Core/ Go 代理、证书服务和定位响应处理
Shared/ 坐标、收藏、日志、配置和共享模型
Resources/ Info.plist、Entitlements 和资源文件
Config/ 构建配置
Scripts/ 构建、打包和验证脚本
Tests/ XCTest 和 Shell contract tests
docs/ 构建、模块和版本文档
```
## 构建项目
源码构建需要 macOS 环境：
- macOS；
- Xcode；
- Xcode Command Line Tools；
- XcodeGen；
- Go 1.23 或更高版本。
当前项目不支持在 Windows 上直接构建 iOS 应用。
```bash ```bash
./build.sh # 构建未签名 IPA git clone https://github.com/xweiba/location-spoofer.git
./build.sh --test # 构建后额外运行 iOS Simulator 单元测试 cd location-spoofer
./build.sh
``` ```
构建产物默认位于： 运行构建并执行 Simulator 测试：
```bash
./build.sh --test
```
构建脚本会生成未签名 IPA：
```text ```text
dist/PaopaoLocationSpoofer-unsigned.ipa dist/PaopaoLocationSpoofer-unsigned.ipa
``` ```
```text 之后需要使用你自己的签名和安装流程部署到测试设备。
App/ SwiftUI、MapKit、定位和配置流程
Core/ Go 本机代理与定位响应改写
Shared/ 收藏、设置、日志和共享模型
Resources/ Info.plist、Entitlements 与图标
Config/ 构建配置
Scripts/ 构建、签名和检查脚本
Tests/ XCTest 与 Bash 契约测试
docs/ 构建、第三方模块和版本发布文档
```
## 文档与反馈 ## 隐私与安全边界
- 项目不包含遥测或远程控制服务；
- 项目不会自动上传用户位置数据；
- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
- 问题报告需要用户主动复制后提交到 GitHub；
- APP 模式会访问本机代理和环境验证地址；
- 第三方代理模式可能访问上游模块地址和 WLOC 配置接口；
- App 生成的 CA 私钥保存在设备 Keychain 中；
- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
## 限制
- iOS 系统版本变化可能影响定位服务行为；
- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
- 系统定位存在缓存，切换位置后不一定立即生效；
- 第三方代理客户端的兼容性和规则行为需要分别验证；
- 不保证所有应用都使用同一种定位 API；
- 不保证所有应用或服务都接受测试坐标；
- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
## 贡献
欢迎提交：
- Bug Report；
- Feature Request；
- 兼容性测试结果；
- 性能改进；
- 文档改进；
- 测试补充。
提交 Issue 时建议包含：
- iOS 版本；
- 设备型号；
- 使用的运行模式；
- 复现步骤；
- 脱敏后的运行日志；
- 是否使用第三方代理客户端。
## 文档
- [构建说明](docs/BUILD.md) - [构建说明](docs/BUILD.md)
- [第三方模块说明](docs/THIRD_PARTY_MODULES.md) - [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
- [更新日志](docs/CHANGELOG.md) - [更新日志](docs/CHANGELOG.md)
- [English README](README.en.md) - [英文文档](README.en.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues) - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
反馈问题时，请附上复现步骤、iOS 版本、设备型号及已脱敏的运行日志。 ## 功能预览
## 友链 以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
影响，不代表对所有应用或版本作出兼容性保证。
**LinuxDo** — [https://linux.do](https://linux.do/) <table>
<tr>
<th>应用主界面</th>
<th>Apple 地图测试</th>
<th>高德地图测试</th>
</tr>
<tr>
<td><img src="images/主界面.jpg" alt="Location Spoofer 地图选点主界面" width="220"></td>
<td><img src="images/Apple%20Map.jpg" alt="Apple 地图定位测试场景" width="220"></td>
<td><img src="images/高德地图.jpg" alt="高德地图定位测试场景" width="220"></td>
</tr>
<tr>
<th>微信测试</th>
<th>钉钉测试</th>
<th>Apple Watch 场景测试</th>
</tr>
<tr>
<td><img src="images/微信.jpg" alt="微信定位测试场景" width="220"></td>
<td><img src="images/钉钉.jpg" alt="钉钉定位测试场景" width="220"></td>
<td><img src="images/高血压.jpg" alt="Apple Watch 地区功能测试场景" width="220"></td>
</tr>
</table>
## 致谢与友链
核心定位响应处理思路、Go 实现和第三方模块参考自：
- [Yu9191/wloc](https://github.com/Yu9191/wloc)
友链：
- [LINUX DO](https://linux.do/)
感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
Scripts/generate-release-notes.sh
+1 -1
View File
@@ -41,7 +41,7 @@ ${COMMITS}
## 自签安装 ## 自签安装
- Release 附件为未签名 IPA，安装前需要自行签名。 - Release 附件为未签名 IPA，安装前需要自行签名。
- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。 - 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
- 签名时请保留 Bundle ID \`com.paopaolabs.location-spoofer\`、App Group \`group.com.paopaolabs.location-spoofer\` 及原有 entitlements。 - 签名时请保留 Bundle ID \`com.paopaolabs.location-spoofer\`、App Group \`group.com.paopaolabs.location-spoofer\` 及原有 entitlements。
- 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。 - 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。
Tests/readme_contract_test.sh
Executable
+62
View File
@@ -0,0 +1,62 @@
#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ZH="$ROOT/README.md"
EN="$ROOT/README.en.md"
fail() { echo "FAIL: $*" >&2; exit 1; }
grep -q 'iOS Location Service Research & Testing Framework' "$ZH" || fail "Chinese README positioning is missing"
grep -q 'iOS Location Service Research & Testing Framework' "$EN" || fail "English README positioning is missing"
grep -q '#### 自签安装说明' "$ZH" || fail "Chinese self-signing instructions are missing"
grep -q '#### Self-Signing Instructions' "$EN" || fail "English self-signing instructions are missing"
grep -q 'Impactor Releases' "$ZH" || fail "Chinese README must link the requested Impactor releases"
grep -q 'Impactor Releases' "$EN" || fail "English README must link the requested Impactor releases"
grep -q '开发者模式' "$ZH" || fail "Chinese README must explain iOS 16 Developer Mode"
grep -q 'Developer Mode' "$EN" || fail "English README must explain iOS 16 Developer Mode"
grep -q '7 天有效期' "$ZH" || fail "Chinese README must disclose free-signing expiry"
grep -q 'seven days' "$EN" || fail "English README must disclose free-signing expiry"
grep -q '^## 功能预览$' "$ZH" || fail "Chinese feature preview is missing"
grep -q '^## Feature Preview$' "$EN" || fail "English feature preview is missing"
images=(
'主界面.jpg'
'Apple%20Map.jpg'
'高德地图.jpg'
'微信.jpg'
'钉钉.jpg'
'高血压.jpg'
)
for image in "${images[@]}"; do
grep -q "images/$image" "$ZH" || fail "Chinese README is missing image: $image"
grep -q "images/$image" "$EN" || fail "English README is missing image: $image"
done
image_files=(
'主界面.jpg'
'Apple Map.jpg'
'高德地图.jpg'
'微信.jpg'
'钉钉.jpg'
'高血压.jpg'
)
for image in "${image_files[@]}"; do
test -f "$ROOT/images/$image" || fail "referenced preview image is missing: $image"
done
test "$(grep -c '^## ' "$ZH")" -eq "$(grep -c '^## ' "$EN")" \
|| fail "Chinese and English README section counts must stay aligned"
! grep -Eq '^## (许可证|License)$' "$ZH" "$EN" || fail "README must not claim a repository license"
grep -q '当前项目不支持在 Windows 上直接构建 iOS 应用' "$ZH" || fail "Chinese README must reject Windows source builds"
grep -q 'Building the iOS app directly on Windows is not supported' "$EN" || fail "English README must reject Windows source builds"
if grep -Rnw --include='*.md' --include='*.sh' \
"$ROOT/build.sh" "$ROOT/README.md" "$ROOT/README.en.md" "$ROOT/docs" "$ROOT/Scripts" \
-e 'Impact'; then
fail "documentation and build output must use the correct Impactor name"
fi
echo "PASS: README contract"
build.sh
+1 -1
View File
@@ -73,4 +73,4 @@ if [ "$run_tests" -eq 1 ]; then
run_simulator_tests run_simulator_tests
fi fi
echo "Next: sign with Impact (https://github.com/claration/Impactor) and install on device." echo "Next: sign with Impactor (https://github.com/claration/Impactor) and install on device."
docs/BUILD.md
+2 -2
View File
@@ -32,12 +32,12 @@ Output:
dist/PaopaoLocationSpoofer-unsigned.ipa dist/PaopaoLocationSpoofer-unsigned.ipa
``` ```
IPA 始终保持未签名。用 [Impact](https://github.com/claration/Impactor) 签名安装即可。 IPA 始终保持未签名。用 [Impactor](https://github.com/claration/Impactor) 签名安装即可。
## 发布验收 ## 发布验收
1. `./build.sh` 通过并输出未签名 IPA 1. `./build.sh` 通过并输出未签名 IPA
2. 用 Impact 签名后安装到设备 2. 用 Impactor 签名后安装到设备
3. 真机安装后，先配置 WiFi HTTP 代理 `127.0.0.1:8888`，再按检测结果完成 CA 下载、安装和信任 3. 真机安装后，先配置 WiFi HTTP 代理 `127.0.0.1:8888`，再按检测结果完成 CA 下载、安装和信任
4. 环境检测通过后，选点开启虚拟定位 4. 环境检测通过后，选点开启虚拟定位
5. 打开 Apple 地图验证定位是否变为虚拟位置 5. 打开 Apple 地图验证定位是否变为虚拟位置
docs/releases/v1.0.0.md
+2 -2
View File
@@ -16,13 +16,13 @@
| 项目 | 要求 | | 项目 | 要求 |
|---|---| |---|---|
| iOS | 15.0+ | | iOS | 15.0+ |
| 安装 | 自行签名（推荐 [Impact](https://github.com/claration/Impactor)） | | 安装 | 自行签名（推荐 [Impactor](https://github.com/claration/Impactor)） |
| 网络 | 可手动配置 HTTP 代理的 WiFi | | 网络 | 可手动配置 HTTP 代理的 WiFi |
### 自签安装 ### 自签安装
1. 从 [Releases](https://github.com/xweiba/location-spoofer/releases) 下载 `PaopaoLocationSpoofer-unsigned.ipa` 1. 从 [Releases](https://github.com/xweiba/location-spoofer/releases) 下载 `PaopaoLocationSpoofer-unsigned.ipa`
2. 使用 [Impact](https://github.com/claration/Impactor) 签名安装 2. 使用 [Impactor](https://github.com/claration/Impactor) 签名安装
3. 签名时保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements 3. 签名时保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements
### 致谢 ### 致谢
docs/releases/v1.0.1.md
+1 -1
View File
@@ -13,7 +13,7 @@
## 自签安装 ## 自签安装
- Release 附件为未签名 IPA，安装前需要自行签名。 - Release 附件为未签名 IPA，安装前需要自行签名。
- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。 - 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
- 签名时请保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements。 - 签名时请保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements。
- 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。 - 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。