luci-app-xray 怎么用？OpenWrt 上先要知道的事

一句话认识 luci-app-xray

luci-app-xray 是运行在 OpenWrt 路由器上的一个 LuCI 网页界面插件，它本身不负责加密和转发，真正干活的是它依赖的 Xray 内核。作者 yichya 在仓库描述中把它称为「（几乎）全功能的 OpenWrt Xray 客户端」，README 开头又补了一句，目标是在保持精简的前提下尽量发挥 Xray 的能力。换句话说，这个插件的定位不是「点一下就能用」的傻瓜工具，而是把 Xray 内核里大量可调的选项，以路由器后台表单的形式摆出来。

如果你只是想在电脑上导入一个订阅链接，这个插件和你关系不大。它适合的是已经在用 OpenWrt、愿意花时间理解透明代理、DNS 分流、防火墙规则的人。对这类用户来说，它的好处是贴近 Xray 原生配置，少了一层转换；坏处是出错时需要自己读日志、自己判断是内核问题还是规则问题。

核对信息表

以下内容来自官方仓库页面、仓库内的 Makefile 与 README，以及 GitHub API 返回的数据。没有在官方渠道看到的字段，统一写「未能核实」。

字段	核对结果	来源
官方仓库	yichya/luci-app-xray	https://github.com/yichya/luci-app-xray
当前版本	3.7.2（仓库 core/Makefile 中的 PKG_VERSION）	仓库 core/Makefile
版本日期	README 更新日志记有 2026-09-08「bump version to 3.7.2」	仓库 README
最近提交	2026-09-22	GitHub API pushed_at 与提交记录
官方 Releases	原仓库 Releases 列表为空，没有作者发布的安装包	GitHub API /releases
平台	OpenWrt 22.03 及以后、使用 firewall4 的固件；软件包标记为 PKGARCH:=all	README 与 core/Makefile
不支持的固件	OpenWrt 22.03 之前版本、Lean 的 OpenWrt 源码	README Warnings 段落
内核	Xray（Makefile 依赖中包含 xray-core）	core/Makefile DEPENDS
其他依赖	firewall4、kmod-nft-tproxy、luci-base、dnsmasq、ca-bundle	core/Makefile DEPENDS
许可证	MPL-2.0	GitHub API license 字段与 Makefile
是否归档	否（archived 为 false）	GitHub API
价格	未能核实（官方页面没有标价，开源项目通常不收费，但本页不作断言）	—

有两点需要特别说明。第一，版本号来自源码里的 Makefile，而不是 Releases 页面，因为原仓库根本没有发布页条目。你在别处看到的「某某版本 ipk 下载」，都不是作者直接发布的。第二，版本日期取自 README 中作者自己写的更新日志，日志里那一条明确写了提升到 3.7.2，这是目前能拿到的最接近「发布日期」的官方记录。

它和 PassWall、OpenClash 有什么不同

站内已经有 PassWall、PassWall2、OpenClash 等路由器插件页面。它们之间最大的分别，在于各自围绕的内核和设计取向。

luci-app-xray 只围绕 Xray 这一个内核来写，界面里的选项几乎都能在 Xray 的配置结构里找到对应项，例如入站类型、FakeDNS、反向代理桥接、额外入站端口等。它没有打算同时兼容多个内核，从 README 的内容看，重点也放在 Xray 原生选项上，而不是订阅与节点管理。OpenClash 则围绕 Clash 系内核，配置文件以 YAML 为主；PassWall 一系则在多个内核之间做调度。如果你对 Xray 的配置字段已经有概念，Xray-core 页面里讲的那些结构，在这个插件里会显得很熟悉；如果你完全没有接触过，先读 OpenClash 或 PassWall 的入门材料，往往更容易上手。

另外一个现实差别是固件门槛。luci-app-xray 要求 firewall4 和客户端渲染的 LuCI，因此大量基于旧版本或 Lean 源码的国产固件直接被排除在外。作者在 README 里说得很直接：这种情况请用 PassWall 或类似项目。所以动手前先确认自己的固件版本，比研究功能更要紧。

用 luci-app-xray 前先读 README 里的几条警告

这个项目的 README 把「Warnings」放在最前面，内容对新用户很有参考价值，这里概括几条：

• 出于安全考虑，监听在所有地址上的全局 SOCKS 与 HTTP 入站已被标记为弃用，计划在 4.0.0 大版本中移除，相关设置已挪进预览应用。作者建议改用「额外入站」手动加端口，并且避开 1080 这类常见端口、仔细设置监听地址。
• 从 3.2.0 起，嗅探与全局自定义设置被标记为弃用，作者建议用 FakeDNS 代替嗅探，用「自定义配置钩子」代替全局自定义设置。
• 对 REALITY 的支持被标为实验性质，可能频繁变动。
• 项目仍处在早期阶段，代码结构、配置文件格式、界面和依赖都可能频繁变化。

最后一条尤其重要。它意味着你今天按某篇教程做好的配置，升级插件后可能需要重新调整。依赖多、变化快的插件，升级前做好备份是基本功，而不是可选项。

luci-app-xray 安装方式与风险提示

官方 README 列出的安装途径有两类。一类是自己编译 OpenWrt 固件时，把该仓库加为软件源，或者直接克隆到 package 目录，然后在「Extra Packages」分类下选中它。另一类是 Fork 仓库后推送标签，让 GitHub Actions 构建安装包，再从你自己 Fork 的 Releases 里取包安装。具体命令请直接照抄官方 README，本页不转述命令参数，避免版本变化后误导读者。

无论选哪种方式，下面几件事都应该在动手前做好：

1. 在系统菜单里导出一份当前配置备份，并保存到电脑上，不要只存在路由器里。不同固件里这个菜单名称略有差异，一般在「系统」下面的备份或升级相关页面。
2. 记下路由器的管理地址和恢复方法。透明代理和防火墙规则一旦写错，可能出现整个局域网断网、后台打不开，甚至插件服务启动失败的情况。
3. 确认存储空间。Xray 内核加上地理数据文件会占用一定空间，小闪存设备可能装不下。README 也提到过缺少 geoip、geosite 数据文件时会出现的警告。
4. 选一个可以接受断网的时间段操作，并准备一台能用有线直连路由器的电脑。

如果操作后出现无法上网，先在后台停用该插件的服务；如果后台已经无法访问，可以尝试固件自带的恢复或重置方式。重置会清掉所有设置，这正是事先备份的意义所在。

预览应用是什么

README 中提到一个「预览应用」。一些已被弃用或尚不稳定的功能，被作者挪到了这个单独的入口里。开启方法是在额外设置中勾选与预览或弃用相关的选项，然后重启路由器，服务菜单下会多出一个预览入口。菜单名称在不同版本中略有差异，请以你实际看到的界面为准。

对普通用户来说，预览应用里的东西更容易在后续版本中被改动或移除，不建议把长期依赖的配置放在那里。

luci-app-xray 与订阅和机场节点

很多人找到这个插件，是想在路由器上用机场订阅。这里要坦白说明：官方 README 的重点是 Xray 的各类入站、出站、DNS 与透明代理选项，本页没有在官方页面中核实到完整的订阅导入说明。插件界面里有没有订阅入口、支持哪种订阅格式，可能随版本变化，请以实际界面和官方 Wiki 为准。

另一个前提是协议匹配。Xray 支持的协议很多，但机场下发的订阅格式五花八门，有的是 Clash 用的 YAML，有的是一行一个分享链接再整体编码。两者能否对接，取决于插件是否做了解析。关于订阅链接的基本结构，可以参考 订阅链接说明；关于各协议之间的区别，可以看 协议总览。如果你只是想让全家设备都走代理，又不想研究这些细节，家庭设备指南里提到的方案或者 OpenClash、Nikki 一类面向订阅的插件，可能更省事。

下载与来源安全

由于原仓库不提供现成安装包，网上流传的 ipk 或 apk 文件来源各异。第三方打包者可能改过代码，也可能夹带其他软件。如果你不打算自己编译，至少要确认打包者的身份和历史，并对照原仓库的版本号与更新日志。更系统的判断方法，可以参考站内的 下载安全指南。

一个简单的原则是：路由器处在整个家庭网络的入口，装在它上面的软件拥有很高的权限。宁可多花一点时间自己构建，也不要随手装一个来历不明的包。

适合谁，不适合谁

适合的人：已经在用 OpenWrt 22.03 或更新版本、固件使用 firewall4；对 Xray 的入站出站结构有基本概念；愿意在升级后花时间检查配置；能够通过日志排查问题。

不适合的人：使用 Lean 源码或旧版固件的设备；只想导入订阅、不想碰任何配置的用户；没有备用上网方式、一旦断网就无法求助的家庭环境。这类情况下，与其硬上这个插件，不如先看站内 客户端总览 里其他更贴合需求的选项。

小结

luci-app-xray 是一个仍在维护、未归档、以 MPL-2.0 许可发布的 OpenWrt 插件，当前源码版本为 3.7.2，底层依赖 Xray 内核。它的特点是贴近 Xray 原生配置、对固件版本要求明确、变化较快。原仓库不发布安装包，需要自行构建或谨慎甄别第三方包。动手之前请备份配置、确认固件版本，并做好可能断网的准备。