# Stash 用户文档

> Stash 用户文档 | Stash 是一款 iOS/tvOS/macOS 平台基于规则的多协议代理客户端，完全兼容 Clash Premium 配置，支持 Rule Set 规则、按需连接、SSID Policy Group、MitM、HTTP 抓包、JavaScript 脚本改写等丰富特性，是 Clash 规则在 iOS 平台的最佳选择。

这是 Stash 的用户文档站。关于如何配置和使用 Stash 的问题——分流规则、代理协议、HTTP 引擎、脚本——都在这里解答。产品与购买信息在 https://stash.ws，英文版文档在 https://stash.wiki/en。

## 快速开始

- [快速上手](https://stash.wiki/get-started): 导入 Stash/Clash 格式的配置文件即可启用 Stash。介绍通过 URL 下载服务商订阅配置，以及导入 iCloud/OneDrive 本地文件两种方式。

## Mac 版

- [Stash Mac](https://stash.wiki/stash-mac): Stash Mac 包含 iOS 版本的全部功能，并针对 macOS 平台提供更多能力。介绍 Mac 独有的功能与使用方式。

## 配置

- [策略组图标](https://stash.wiki/configuration/proxy-group-icon): 在配置文件的 proxy-groups 中通过 icon 字段为策略组指定图标，支持 JPG 与 PNG 格式的图片 URL。
- [覆写文件（Override）](https://stash.wiki/configuration/override): 覆写文件（Override）用于修改托管或订阅配置中的部分字段。介绍声明方式、多个覆写文件从上到下的叠加顺序，以及让用户自行填写的覆写参数。
- [配置样例](https://stash.wiki/configuration/example-config): 完整的 Stash YAML 配置文件样例，逐段说明各字段的作用与写法，可直接作为编写自有配置的起点。

## 代理协议

- [代理链](https://stash.wiki/proxy-protocols/dialer-proxy): 代理链（dialer-proxy）用于指定上游代理，使连接先经由另一个代理转发，可中继 TCP 与 UDP。
- [协议类型](https://stash.wiki/proxy-protocols/proxy-types): Stash 支持的代理协议类型完整列表，涵盖 TCP 与 UDP 代理，以及各协议的配置字段说明。
- [延迟测试](https://stash.wiki/proxy-protocols/proxy-benchmark): 为每个代理单独设置延迟测试参数，包括延迟测试的目标 URL 与超时时间。
- [策略组](https://stash.wiki/proxy-protocols/proxy-groups): 策略组（proxy-groups）是一系列代理或策略组的组合，可像单个代理一样被分流规则引用。介绍各类策略组与配置方式。
- [远程代理集](https://stash.wiki/proxy-protocols/proxy-providers): 远程代理集（proxy-provider）可在后台自动从 URL 更新代理列表，无需手动修改配置文件。

## 规则

- [规则类型](https://stash.wiki/rules/rule-types): Stash 支持的分流规则类型完整说明，可按 IP、域名、进程名或组合多个条件匹配连接，并指定出站方式。
- [规则集合](https://stash.wiki/rules/rule-set): 规则集合（rule-providers）以较低的资源占用引用大量规则，并支持后台静默更新而无需重新加载 Stash。

## HTTP 引擎

- [Force HTTP Engine](https://stash.wiki/http-engine/force-http-engine): 配置 force-http-engine 让来自 Tunnel 的 TCP 连接同样经由 HTTP 引擎处理，以便使用改写与脚本功能。
- [HTTP 重写](https://stash.wiki/http-engine/rewrite): HTTP 重写通过正则表达式匹配 URL，拒绝或重定向 HTTP(S) 请求，常用于去广告与阻断隐私跟踪。
- [MitM](https://stash.wiki/http-engine/mitm): 启用 MitM 后即可查看、改写 HTTPS 请求并执行脚本。介绍 CA 证书的生成、导入以及设备信任的完整步骤。
- [Stash HTTP Engine](https://stash.wiki/http-engine/intro): Stash 内置高效的 HTTP 引擎，可对系统中的 HTTP 请求进行改写、拦截、抓取与重放，并通过 MitM 方式解密 HTTPS 请求。

## 脚本

- [定时任务](https://stash.wiki/script/scheduled-tasks): Stash 可在后台执行 JavaScript 定时任务，需要 Network Extension 处于已连接状态。
- [改写 HTTP](https://stash.wiki/script/rewrite-requests): 使用 JavaScript 脚本修改流经 Stash 的 HTTP 请求与响应。介绍脚本的编写方式与生效条件。
- [管理脚本](https://stash.wiki/script/manage-script): 通过 script-providers 管理脚本，声明后即可在改写、面板与定时任务中引用。
- [语法与接口](https://stash.wiki/script/syntax-and-interface): Stash 脚本的语法与可用接口说明，包括所有脚本结束时必须调用的 $done(value) 方法。
- [面板 (Tile)](https://stash.wiki/script/tile): 通过 JavaScript 脚本自定义 Stash 首页的 Tile 面板，展示你需要的信息。

## 功能

- [HTTP API](https://stash.wiki/features/http-api): Stash 提供 HTTP 控制 API，可查询状态、切换策略、刷新资源、诊断 DNS 与代理，并兼容 Clash 控制接口。
- [MTProto 代理服务器](https://stash.wiki/features/mtproto): Stash 内置 MTProto 代理服务器，Telegram 客户端可直接连接 Stash，由 Stash 选择数据中心地址并按分流规则转发。
- [为局域网设备提供代理](https://stash.wiki/features/provide-proxy-to-lan-device): Stash iOS、tvOS 与 Stash Mac 均可为局域网中的其他设备提供代理服务。介绍开启方式与客户端配置方法。
- [主机名映射](https://stash.wiki/features/hosts): 主机名映射功能可将域名解析到指定 IP 地址，或将 A 域名的解析映射为 B 域名的解析。介绍 hosts 字段的写法。
- [内网穿透](https://stash.wiki/features/nat-traversal): Stash 内置 StashLink 与 Tailscale 两套内网穿透方案：StashLink 零配置连接同一 iCloud 账号下的设备，Tailscale 支持跨平台的复杂组网。
- [内置 DNS 服务](https://stash.wiki/features/dns-server): Stash 内置 DNS 服务，支持同时配置多个服务器并采用最快响应的结果。介绍支持的 DNS 协议与配置方式。
- [按需启动](https://stash.wiki/features/on-demand): 按需启动让 Stash 保持持续运行状态。介绍该选项的行为，以及如何通过 App 内的停止按钮关闭。
- [服务提供商订阅](https://stash.wiki/features/service-provider-subscription): Stash 支持由服务提供商管理的配置，可定时更新配置文件，并显示服务剩余流量与过期信息。
- [网络性能增强](https://stash.wiki/features/network-performance-enhance): Stash 在网络连接各个层面的性能优化说明，包括降低延迟与提升吞吐的具体机制。

## 常见问题

- [IPv6 兼容性](https://stash.wiki/faq/ipv6-compatible): Stash 的 IPv6 兼容性说明。Stash 会根据系统返回的 IPv4 / IPv6 状态自动选择最佳连接策略，通常无需手动启用。
- [Stash 与其他 VPN 的冲突解决方法](https://stash.wiki/faq/conflict-with-vpn): Stash 与其他 VPN 同时使用时的冲突解决方法，通过绑定网卡的方式让两者共存。
- [TestFlight 相关问题](https://stash.wiki/faq/testflight): Stash 通过 TestFlight 分发 Beta 版本。介绍购买用户如何申请参与测试，以及 TestFlight 版本的常见问题。
- [URL Schema](https://stash.wiki/faq/url-schema): Stash 支持通过 stash:// 与 clash:// URL Schema 控制应用。介绍可用的 URL 指令，以及参数的 Encode 要求。
- [授权与激活](https://stash.wiki/faq/license-activation): Stash 授权（License）的激活方式与设备数量限制说明，以及如何管理已激活的设备。
- [无法安装 Stash Mac 帮助程序 (Helper)](https://stash.wiki/faq/stash-mac-helper): Stash Mac 反复提示安装帮助程序（Helper）的原因与解决方法。帮助程序用于以管理员权限设置系统代理。
- [无法收到部分应用的推送通知](https://stash.wiki/faq/ios-push-notifications): 部分海外应用在中国大陆网络下收不到推送通知的原因与处理方式，涉及 APNs 服务与网络出口的关系。
- [编写高效的配置文件](https://stash.wiki/faq/effective-stash): iOS Network Extension 有 15 MB / 50 MB 的内存限制。介绍如何编写高效的配置文件，避免 Stash 因超出内存被系统关闭。
- [越狱 iOS 系统内存限制修改](https://stash.wiki/faq/jailbreak-ios-memory-limit): 在越狱 iOS 设备上修改 Jetsam 内存限制的方法，用于提升 Network Extension 可用的内存上限。
- [防止代理被检测](https://stash.wiki/faq/proxy-detected): 使用「仅使用 Tunnel 代理」模式防止应用程序检测到代理环境，适用于会拒绝在代理下运行的应用。

## 更新日志

- [iOS](https://stash.wiki/release-notes/ios): Stash iOS 版本更新日志，记录各版本的新增功能、改进与问题修复。
- [macOS](https://stash.wiki/release-notes/macos): Stash Mac 版本更新日志，记录各版本的新增功能、改进与问题修复。
- [tvOS](https://stash.wiki/release-notes/tvos): Stash tvOS 版本更新日志，记录各版本的新增功能、改进与问题修复。

---

# Stash Wiki

> Stash Wiki | Stash is a rule-based multi-protocol proxy client for iOS/macOS platforms, fully compatible with Clash Premium configuration, supporting Rule Set rules, on-demand connection, SSID Policy Group, MitM, HTTP capture, JavaScript script rewriting and other rich features, making it the best choice for Clash rules on iOS platform.

This is the Stash user manual. Questions about configuring and using Stash — rules, proxy protocols, the HTTP engine, scripting — are answered here. Product and pricing information is at https://stash.ws, and the Chinese edition of this manual is at https://stash.wiki/.

## Getting started

- [Quick Start](https://stash.wiki/en/get-started): Enable Stash by importing a Stash/Clash configuration file. Covers downloading a provider subscription by URL and importing a local file from iCloud or OneDrive.

## Stash for Mac

- [Stash Mac](https://stash.wiki/en/stash-mac): Stash Mac includes every feature of the iOS version, plus capabilities built specifically for macOS. Covers what the Mac app adds and how to use it.

## Configuration

- [Configuration Example](https://stash.wiki/en/configuration/example-config): A complete Stash YAML configuration example, explaining each field section by section — a working starting point for writing your own.
- [Override](https://stash.wiki/en/configuration/override): Override files modify individual fields in a managed or subscribed configuration. Covers how to declare them, the top-to-bottom order in which multiple overrides apply, and override parameters users fill in themselves.
- [Proxy Group Icon](https://stash.wiki/en/configuration/proxy-group-icon): Give each proxy group an icon by adding an icon field under proxy-groups in your configuration, pointing at a JPG or PNG image URL.

## Proxy protocols

- [Delayed Testing](https://stash.wiki/en/proxy-protocols/proxy-benchmark): Set latency test parameters per proxy, including the target URL used for the test and its timeout.
- [Dialer Proxy](https://stash.wiki/en/proxy-protocols/dialer-proxy): Dialer proxy chains connections through an upstream proxy before reaching the target server, relaying both TCP and UDP.
- [Protocol Types](https://stash.wiki/en/proxy-protocols/proxy-types): The full list of proxy protocols Stash supports, covering both TCP and UDP proxies along with the configuration fields for each.
- [Remote Proxy Set](https://stash.wiki/en/proxy-protocols/proxy-providers): A remote proxy provider updates its proxy list from a URL in the background, so the configuration file does not have to be edited by hand.
- [Strategy Group](https://stash.wiki/en/proxy-protocols/proxy-groups): A proxy group (proxy-groups) combines proxies or other groups and can be referenced by rules like a single proxy. Covers each group type and how to configure it.

## Rules

- [Rule Sets](https://stash.wiki/en/rules/rule-set): Rule sets (rule-providers) reference large rule lists with low resource use and update silently in the background without reloading Stash.
- [Rule Types](https://stash.wiki/en/rules/rule-types): The full set of rule types Stash supports. Match connections by IP, domain, process name or a combination of conditions, and choose their outbound path.

## HTTP engine

- [Force HTTP Engine](https://stash.wiki/en/http-engine/force-http-engine): Configure force-http-engine so TCP connections arriving from the Tunnel also pass through the HTTP engine, making rewrites and scripts available to them.
- [HTTP Rewrite](https://stash.wiki/en/http-engine/rewrite): HTTP rewriting matches URLs with regular expressions to reject or redirect HTTP(S) requests — commonly used to block ads and privacy tracking.
- [MitM](https://stash.wiki/en/http-engine/mitm): Enabling MitM lets you inspect and rewrite HTTPS requests and run scripts against them. Covers generating or importing the CA certificate and trusting it on your device.
- [Stash HTTP Engine](https://stash.wiki/en/http-engine/intro): Stash's built-in HTTP engine rewrites, intercepts, captures and replays HTTP requests, and decrypts HTTPS requests through MitM.

## Scripting

- [Manage Scripts](https://stash.wiki/en/script/manage-script): Manage scripts through script-providers. Once declared, a script can be referenced from rewrites, tiles and scheduled tasks.
- [Panel (Tile)](https://stash.wiki/en/script/tile): Customise the Tile panel on the Stash home screen with JavaScript to surface the information you care about.
- [Rewrite HTTP](https://stash.wiki/en/script/rewrite-requests): Modify the HTTP requests and responses flowing through Stash with JavaScript. Covers how to write these scripts and what makes them take effect.
- [Scheduled Tasks](https://stash.wiki/en/script/scheduled-tasks): Stash runs JavaScript scheduled tasks in the background, which require the Network Extension to be connected.
- [Syntax and Interface](https://stash.wiki/en/script/syntax-and-interface): Syntax and available interfaces for Stash scripts, including the $done(value) call every script must make to release resources.

## Features

- [Built-in DNS Service](https://stash.wiki/en/features/dns-server): Stash's built-in DNS service queries multiple servers at once and takes the fastest response. Covers the supported DNS protocols and how to configure them.
- [HTTP API](https://stash.wiki/en/features/http-api): Stash exposes an HTTP control API for querying state, switching policies, refreshing resources, and diagnosing DNS and proxies, compatible with the Clash control API.
- [Hostname Mapping](https://stash.wiki/en/features/hosts): Hostname mapping resolves a domain to a specific IP address, or maps one domain's resolution to another. Covers the syntax of the hosts field.
- [MTProto Proxy Server](https://stash.wiki/en/features/mtproto): Stash includes an MTProto proxy server: Telegram clients connect to Stash directly, and Stash picks the data center address and routes the connection by your rules.
- [NAT Traversal](https://stash.wiki/en/features/nat-traversal): Stash ships two built-in NAT traversal solutions: StashLink connects devices under the same iCloud account with zero configuration, while Tailscale enables complex cross-platform networking.
- [Network Performance Enhancement](https://stash.wiki/en/features/network-performance-enhance): How Stash optimises each layer of the network connection to deliver low latency and high throughput.
- [On-Demand Activation](https://stash.wiki/en/features/on-demand): On-Demand activation keeps Stash running continuously. Covers how the option behaves and how to stop Stash once it is enabled.
- [Providing Proxy for Local Area Network Devices](https://stash.wiki/en/features/provide-proxy-to-lan-device): Stash on iOS, tvOS and macOS can serve as a proxy for other devices on your local network. Covers enabling it and configuring the client devices.
- [Service Provider Subscription](https://stash.wiki/en/features/service-provider-subscription): Stash supports configurations managed by a service provider, updating them on a schedule and showing remaining traffic and expiry information.

## FAQ

- [Authorization and Activation](https://stash.wiki/en/faq/license-activation): How Stash licenses are activated, the device limit that applies to each one, and how to manage the devices already activated.
- [IPv6 Compatibility](https://stash.wiki/en/faq/ipv6-compatible): IPv6 compatibility in Stash. Stash picks the best connection strategy automatically from the IPv4 / IPv6 status the system reports, so enabling it by hand is rarely needed.
- [Modify the memory limit of the iOS system for jailbroken devices](https://stash.wiki/en/faq/jailbreak-ios-memory-limit): How to change the Jetsam memory limit on jailbroken iOS devices to raise the ceiling available to the Network Extension.
- [Prevent Detection of Proxy](https://stash.wiki/en/faq/proxy-detected): Use Tunnel-only proxy mode to keep apps from detecting a proxy environment — useful for apps that refuse to run behind one.
- [Stash Conflict with Other VPNs](https://stash.wiki/en/faq/conflict-with-vpn): How to resolve conflicts between Stash and other VPN apps by binding the network interface so both can run together.
- [TestFlight Related Issues](https://stash.wiki/en/faq/testflight): Stash ships beta builds through TestFlight. How purchasers join the test, and the questions that come up most often with TestFlight builds.
- [URL Schema](https://stash.wiki/en/faq/url-schema): Stash can be controlled through the stash:// and clash:// URL schemas. Covers the available commands and the encoding required for parameters.
- [Unable to Install Stash Mac Helper](https://stash.wiki/en/faq/stash-mac-helper): Why Stash Mac keeps asking to install the Helper, and how to resolve it. The Helper is what sets the system proxy with administrator privileges.
- [Unable to Receive Push Notifications from Some Apps](https://stash.wiki/en/faq/ios-push-notifications): Why some overseas apps stop receiving push notifications on mainland China networks, and what to do about it — the cause lies with APNs and your network egress.
- [Writing Efficient Configuration Files](https://stash.wiki/en/faq/effective-stash): The iOS Network Extension is capped at 15 MB / 50 MB of memory. How to write an efficient configuration file so iOS does not terminate Stash for exceeding it.

## Release notes

- [iOS](https://stash.wiki/en/release-notes/ios): Release notes for Stash on iOS, listing new features, improvements and fixes in each version.
- [macOS](https://stash.wiki/en/release-notes/macos): Release notes for Stash on macOS, listing new features, improvements and fixes in each version.
- [tvOS](https://stash.wiki/en/release-notes/tvos): Release notes for Stash on tvOS, listing new features, improvements and fixes in each version.