Windows
macOS
LinuxXray-core 适合哪些使用场景
如果你需要管理进程、阅读 JSON 配置，或理解图形客户端背后的连接过程，可以直接使用 Xray-core。只想导入配置并切换节点的用户，可先看 v2rayN 指南或 v2rayNG 指南。
内核、配置和远端服务是三件事。安装内核不会自动获得服务器地址或凭据；配置通过检查，也不能证明远端可达。先把本机监听、请求转发和日志对应起来，再接入你有权使用的远端配置。
从官方发行页选择系统与架构
进入 Xray-core 官方 Releases，阅读所选版本说明，然后下载匹配系统与处理器架构的压缩包。Windows、Linux 与 macOS 包不能混用；Intel/AMD 电脑与 ARM 设备也要分别选择。
- 解压到自己容易找到的目录，并保留随包文件；不要只凭文件名从第三方网盘下载。
- 在解压目录打开终端。下文假设命令已加入 PATH；否则 macOS/Linux 用
./xray，Windows 用.\xray.exe代替xray。 - 执行
xray version和xray help run，确认运行的是刚下载的程序。
系统无法运行时，先核对架构、操作系统要求和可执行权限，再考虑配置。已有客户端捆绑的内核与单独下载的版本可能不同，不应只根据客户端版本推断内核能力。
创建仅供本机使用的最小配置
在程序目录新建 UTF-8 文本文件 config.json，保存以下完整 JSON。这里用两个不同端口，方便区分 HTTP 和 SOCKS 请求；若端口已被占用，可同时修改配置与后面的验证命令。
{
"log": { "loglevel": "warning" },
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
},
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
],
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
}listen 固定为 127.0.0.1，只接受本机连接；不要为了“连不上”直接改成公网监听。本例 SOCKS 不启用 UDP，HTTP 入站用于本机应用。唯一出站 freedom 直接连接目标，没有连接远端代理，也不会改变出口位置。
先检查配置，再启动进程
先执行检查命令；检查通过后再执行启动命令，两者不要同时输入：
xray run -test -config ./config.json
xray run -config ./config.json-test 只验证配置能否加载，不启动监听。出现错误时按提示检查 JSON 标点、路径和当前版本支持的字段。启动命令会持续运行，终端暂时没有新输出并不代表失败。保留这个终端，在另一个终端验证；结束演示时用 Ctrl+C 停止。
如果启动时报告地址已被使用，说明该端口已有其他进程。优先停止自己的重复实例或换一个空闲端口，不要结束不认识的系统进程。
分别验证 HTTP 与 SOCKS 入口
以下请求访问文档示例域名，限制最长等待时间，不更改系统代理。macOS/Linux 使用 curl；Windows PowerShell 使用 curl.exe，避免同名命令别名。
curl --noproxy localhost --proxy http://127.0.0.1:10809 --head --max-time 20 https://example.com
curl --noproxy localhost --proxy socks5h://127.0.0.1:10808 --head --max-time 20 https://example.com--noproxy localhost 明确限定绕过列表，示例目标仍走指定入口；socks5h 把目标域名交给内核解析。观察命令是否连接本机端口、是否拿到目标的 HTTP 响应头。具体状态码由目标实时返回，不预设固定结果。
HTTP 代理可能先显示 CONNECT 隧道响应，随后才是目标响应。拿到页面响应只证明这次本机转发成功；它不能证明远端节点、系统所有应用或 UDP 工作正常。
验证记录：2026 年 10 月 2 日，官方 Linux amd64 版 Xray 26.3.27 运行此配置得到 Configuration OK，HTTP 与 SOCKS 两次示例请求均完成并收到目标 HTTP 200。测试后已停止本机进程。该记录覆盖这个版本、环境和当次请求；其他系统、目标与远端配置仍需分别验证。
按错误发生的层次排查
| 现象 | 优先检查 |
|---|---|
| 连接本机端口被拒绝 | 进程是否运行，命令端口是否与配置一致，启动日志是否报错。 |
| 配置检查失败 | 实际文件路径、JSON 格式、字段与运行版本；保留完整错误行。 |
| 本机已连接，目标超时 | 当前直连网络、目标状态和域名解析；这不是远端代理故障。 |
| 只有某个应用无效 | 应用是否使用该入口，以及它需要 HTTP、SOCKS 还是其他方式。 |
需要更多信息时临时把 loglevel 改为 info 并重启，复现一次后恢复。日志可能包含访问域名与地址；反馈问题时提供版本、命令和必要错误，遮盖凭据及个人路径。更多连接分层思路可见 故障排查。
接入真实配置前确认兼容与维护方式
本机演示完成后，如需远端连接，应根据真实服务提供的协议、地址、端口、身份信息和传输设置配置出站，并以当前官方文档为准。不要把其他内核的 YAML、订阅文本或客户端配置直接当作 Xray JSON。
修改前备份原文件，修改后重复配置检查与单次请求验证。更新内核时阅读发行说明，保留可回退版本，并重新检查已有配置。日常客户端管理可用图形工具；路由定位用 NextTrace，DNS 对照用 doggo。
常见问题
Xray-core 与 v2rayN 是同一种软件吗？
不是。Xray-core 是处理连接和转发的内核；v2rayN 提供图形操作界面，并可调用内核。内核本身没有节点列表和一键导入界面。
为什么这个示例的出口 IP 没有变化？
示例只有 freedom 直连出站，用来验证本机监听与请求转发。它没有远端代理出站，出口没有变化属于设计行为。
配置检查通过，为什么启动仍失败？
-test 不会启动监听。端口占用、执行权限或启动环境可能在真正运行时才暴露，应查看启动时的错误提示。
可以让局域网设备连接这里的 SOCKS 端口吗？
本例明确只监听 127.0.0.1，其他设备无法连接。局域网共享涉及监听地址、认证和防火墙；不要直接把无认证入口开放到公网。
为什么 Windows 的 curl 命令行为不同？
部分 PowerShell 环境把 curl 作为其他命令的别名。使用 curl.exe 调用真正的 curl，并确认使用的代理协议与端口匹配。
官方来源与核对
本文依据以下官方项目与文档整理，资料核对日期为 2026.10.02。安装包、界面和配置字段会随版本变化，可通过原始资料确认当前要求。