1. 安装
源代码版本需要 Python 3.11 或更高版本。可以直接从 PyPI 安装：
pip install PyProxySwitch推荐使用 pipx 创建隔离环境，同时让命令全局可用：
pipx install PyProxySwitch也可以直接安装 Git 仓库：
pip install git+https://github.com/Kder/PyProxySwitch.git安装会自动拉取 PySide6 与 platformdirs。
2. 启动
安装后运行 pyproxyswitch 启动图形界面，或使用 pyproxyswitch-cli 命令入口。源码目录也可以直接运行：
python PyProxySwitch.py
python -m pyproxyswitch首次启动会在当前用户配置目录创建 PPS.conf 和 proxy.txt，不会写入 site-packages。
3. 配置网络应用
把应用的 HTTP/HTTPS 代理或 SOCKS 代理设置为：
地址：127.0.0.1
端口：8888这是 PyProxySwitch 的本地入口，不是上游代理地址。HTTP、SOCKS4/SOCKS4a 和 SOCKS5 客户端可以共用这个端口。若应用分别要求“HTTP 代理”和“HTTPS 代理”，两者均可填写该地址；HTTPS 会使用 CONNECT 隧道。
4. 添加上游代理
双击托盘图标，或右击后选择“设置”。在表格中添加代理名称、地址、端口、协议以及可选认证信息。支持的上游类型为 HTTP、SOCKS4 和 SOCKS5。
也可以直接编辑当前用户配置目录中的 UTF-8 proxy.txt。每行格式为“代理名称 代理地址:端口 用户名:密码 代理类型”：
test1 test1.com:8080
test2 test2.com:8080 user:pass
test3 1.2.3.4:80
socks_proxy socksproxy.com:3128 SOCKS5认证信息和代理类型均可省略；省略类型时默认为 HTTP。代理列表在运行时直接读取，不再生成第三方后端的配置文件。
5. 切换路由
右击系统托盘图标并选择上游。选择 NoProxy 表示直接连接目标，不经过上游代理。
上游切换不重启本地端口。切换时已经建立的连接继续使用原上游；此后建立的新连接使用新上游。因此测试切换结果时，请新开连接或重新加载应用。
为避免意外成为局域网公开代理，默认只监听 127.0.0.1。确需调整时，在 PPS.conf 中显式设置 LOCAL_ADDRESS，并同时配置适当的防火墙和访问边界。
6. 便携模式
便携模式把配置和日志保存在程序目录中，不向系统用户目录写入应用数据。Windows 单目录版解压后即可运行；包内的 portable.ini 会让配置写入 config/、日志写入 logs/。删除该标记即可恢复系统用户目录。
源码、pip 和 exe 运行方式都可将环境变量 PYPROXYSWITCH_HOME 指向便携目录。路径优先级为：
PYPROXYSWITCH_HOME > portable.ini（仅冻结程序） > 系统用户目录维护者可运行 uv run --group build python tools/build_nuitka.py；uv 会按项目的 build 依赖组安装 Nuitka 并生成 Windows 便携 zip。编译中间文件写入 build/nuitka/，最终目录和 zip 写入 release/。
7. 卸载与数据清理
pip uninstall PyProxySwitch
# 使用 pipx 安装时：
pipx uninstall PyProxySwitch卸载命令只移除程序和命令入口，按 Python 应用惯例保留用户配置与日志。需要彻底删除时，再手动清理：
- Windows 配置：
%APPDATA%\Kder\PyProxySwitch - Windows 日志：
%LOCALAPPDATA%\Kder\PyProxySwitch\Logs，或PPS.conf中LOG_PATH指定的目录 - Linux：
~/.config/PyProxySwitch与~/.local/state/PyProxySwitch/log - macOS：
~/Library/Application Support/PyProxySwitch与~/Library/Logs/PyProxySwitch
通过 pip 安装时，PySide6、platformdirs 等依赖也会保留，不再需要时请另行卸载。便携版只需删除程序文件夹。
命令行选项
pyproxyswitch --version
pyproxyswitch --log-level DEBUG--log-level 可选 DEBUG、INFO、WARNING 或 ERROR，用于覆盖本次启动的控制台日志级别。
退出
从托盘菜单选择“退出”。程序会停止接受新连接，并妥善结束本地代理服务。关闭设置窗口不会退出托盘程序。