HongShi AI正在绞尽脑汁想思路ING···

HongShiのAI摘要

GPT-4o

在手机上搭建KVideo

HongShi2026-02-082026-02-08

首先感谢KuekHaoYang对KVideo的开发，仓库地址：https://github.com/KuekHaoYang/KVideo

最近发现了一个非常酷的开源项目 KVideo——一个基于 Next.js 构建的现代化视频聚合播放平台，拥有独特的“液态玻璃”UI 设计。既然是 Next.js 项目，能不能不依赖电脑，直接在安卓手机上跑起来呢？

答案是肯定的！利用 Termux 这款强大的终端模拟器，我们完全可以在手机上搭建一个本地 Node.js 环境。虽然过程踩了不少坑，但最终成功运行的那一刻，成就感拉满。本文将详细记录从 0 到 1 的部署过程，希望能帮到同样喜欢折腾的朋友。

观前声明：此方法仅适用于安卓平台，且占用空间较大（大约为800MB）,且后期升级可能会有兼容性问题，如出现报错请自行解决。

1. 安装 Termux

千万不要在 Google Play 商店下载 Termux，那里的版本已经很久没更新了，兼容性很差。

正确姿势：去官网下载安装最新版 Termux。

仙人指路：Termux官方站

KVideo 是基于 Node.js 的，我们需要安装它以及 Git 工具来拉取代码：

1	pkg install nodejs git

2. 安装核心环境

在安装依赖，由于国内网络环境，直接 npm install 经常会出现 ECONNRESET 错误。

解决方案：切换到淘宝 NPM 镜像源，速度飞快且稳定。

# 切换镜像源
npm config set registry https://registry.npmmirror.com
# 清理残留
rm -rf node_modules package-lock.json
# 重新安装
npm install --ignore-scripts

安装完后可输入

1 2	node -v npm -v

查看是否安装成功。

3. 克隆项目代码

使用 git 命令将 KVideo 的源码拉取到本地：

1 2	git clone https://github.com/KuekHaoYang/KVideo.git cd KVideo

4. 安装依赖

注意，这里用通用代码部署会遇到兼容性问题，这一部分会解决这些问题，如果本篇文章给出的解决方案不可行，请自行问AI解决。

直接运行 npm install 会报错，因为项目包含 Cloudflare 的部署工具（workerd），它不支持安卓平台。

解决方案：使用 --ignore-scripts 参数跳过安装脚本，只下载必要的代码包。

1	npm install --ignore-scripts

KVideo 默认使用 Next.js 16，其默认的 Turbopack 打包器在安卓 ARM64 架构下存在兼容性问题（turbo.createProject is not supported），导致无法启动开发模式。

解决方案：我们需要手动降级到 Next.js 15，它使用兼容性更好的 Webpack。

# 降级 Next.js 到 15.x (使用通配符 .* 自动匹配当前版本)
sed -i 's/"next": ".*"/"next": "^15.1.0"/g' package.json
# 为了稳妥，同步降级 React 到 18.x
sed -i 's/"react": ".*"/"react": "^18.3.1"/g' package.json
sed -i 's/"react-dom": ".*"/"react-dom": "^18.3.1"/g' package.json
# 清理并重新安装
rm -rf node_modules package-lock.json
npm install --ignore-scripts

5. 启动项目

万事俱备，启动服务！

在安卓环境下，Next.js 会尝试下载不存在的安卓版原生二进制文件（@next/swc-android-arm64），导致启动时报错 Error: request failed with status 404。
解决方案：我们需要修改下载逻辑，让它在下载失败时静默返回 null，而不是报错崩溃。

node -e "const fs=require('fs'); fs.writeFileSync('node_modules/next/dist/lib/download-swc.js', fs.readFileSync('node_modules/next/dist/lib/download-swc.js','utf8').replace(/throw Object\.defineProperty.*?\);/gs, 'return null;'))"

修复完成后，执行以下命令启动服务（为了演示方便，这里注入了一个测试订阅源）：

1	export NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"默认订阅源","url":"https://raw.githubusercontent.com/rapier15sapper/ew/refs/heads/main/test.json"}]' && npm run dev

当终端出现 Ready on http://localhost:3000 时，说明服务已成功启动。

6. 订阅源

如果不使用上方测试源，可以自行配置订阅源。

例如，使用以下命令设置你自己的源：

1	export NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"我的源","url":"你的订阅源地址"}]'

然后重新启动服务：

1	npm run dev

如果想要停止，只需要按一下下方的CTRL，然后在英文状态下输出c即可。

7. 空间清理

你在运行完命令后termux大概率会占据你手机一个GB以上的空间，这是不好的，我们需要进行一些清理。

1.清理构建缓存

注意：这个.next文件夹会在每次运行完之后生成，所以每次结束后都要清理

1	rm -rf .next

2.清理下载失败残留

1	rm -rf /data/data/com.termux/files/usr/tmp/next-swc

3.清理node_modules

1	npm cache clean --force

一套组合拳下来，我的内存占用到了885MB（包含软件本体）

8. 一键懒人脚本

我知道有些人肯定很烦跟着教程一步一步走，也懒得听原理是什么，所以这里提供一键懒人脚本，一键搞定。
安装脚本：

pkg install nodejs git -y && \
git clone https://github.com/KuekHaoYang/KVideo.git && \
cd KVideo && \
echo "[1/6] 正在切换为淘宝镜像源..." && \
npm config set registry https://registry.npmmirror.com && \
echo "[2/6] 正在降级 Next.js 和 React 版本以适配安卓..." && \
sed -i 's/"next": ".*"/"next": "^15.1.0"/g' package.json && \
sed -i 's/"react": ".*"/"react": "^18.3.1"/g' package.json && \
sed -i 's/"react-dom": ".*"/"react-dom": "^18.3.1"/g' package.json && \
echo "[3/6] 正在安装依赖包 (这可能需要几分钟)..." && \
npm install --ignore-scripts && \
echo "[4/6] 正在应用安卓环境修复补丁..." && \
node -e "const fs=require('fs'); fs.writeFileSync('node_modules/next/dist/lib/download-swc.js', fs.readFileSync('node_modules/next/dist/lib/download-swc.js','utf8').replace(/throw Object\.defineProperty.*?\);/gs, 'return null;'))" && \
echo "[5/6] 注入测试订阅源..." && \
export NEXT_PUBLIC_SUBSCRIPTION_SOURCES='[{"name":"默认订阅源","url":"https://raw.githubusercontent.com/rapier15sapper/ew/refs/heads/main/test.json"}]' && \
echo "[6/6] 启动服务..." && \
npm run dev

一键垃圾清理脚本：

1
2
3

rm -rf .next && \
rm -rf /data/data/com.termux/files/usr/tmp/next-swc && \
npm cache clean --force

本文同步发布于手机部署Kvideo？天哪这是接近的！ - 开发调优 - LINUX DO