在 Termux 上配置 Cloudflare Wrangler，并上传已有 Worker 与 D1 数据库

在 Termux 上配置 Cloudflare Wrangler，并上传已有 Worker 与 D1 数据库#

本教程按“完全不会 Wrangler 的新手”来写。
目标是让你最终可以只使用 Android 手机上的 Termux，完成：

安装 Wrangler

登录 Cloudflare

查看已经创建好的 Worker

查看已经创建好的 D1

上传 .sql 数据库

将 .db / .sqlite 数据库转换为 SQL 后导入

部署 Worker

检查 D1 是否导入成功

本教程使用 Termux → Ubuntu 24.04 → Node.js 24 → Wrangler 这条路线。这样可以绕开原生 Android/Termux 环境下 Wrangler 原生依赖可能带来的兼容性问题。

目录#

一、先理解整个流程
二、第一步：更新 Termux
三、第二步：安装 Ubuntu 2404
四、第三步：进入 Ubuntu
五、第四步：给 Termux 访问手机存储的权限
六、第五步：更新 Ubuntu 并安装基础工具
七、第六步：安装 NVM
八、第七步：安装 Node.js 24
九、第八步：安装 Wrangler
十、第九步：登录 Cloudflare
十一、第十步：检查登录状态
十二、第十一步：查看已有 D1
十三、第十二步：查看 D1 详细信息
十四、第十三步：获取已经创建好的 Worker
十五、第十四步：进入 Worker 项目
十六、第十五步：检查 Wrangler 配置
十七、第十六步：理解 D1 Binding
十八、第十七步：备份现有 D1
十九、第十八步：上传 SQL 数据库
二十、第十九步：如果手里的是 db/sqlite 文件
二十一、第二十步：检查 D1 数据
二十二、第二十一步：部署 Worker 前先测试
二十三、第二十二步：正式部署 Worker
二十四、第二十三步：以后怎么更新 Worker
二十五、常见问题
二十六、完整命令速查
二十七、参考资料

一、先理解整个流程#

我们最终的环境大概是：

1
Android 手机
2
└── Termux
3
    └── Ubuntu 24.04
4
        ├── Node.js 24
5
        ├── npm
6
        └── Wrangler
7
            ├── Cloudflare Worker
8
            └── Cloudflare D1

以后你更新 Worker 时，基本只需要：

1
npx wrangler deploy --keep-vars

如果要把 SQL 导入 D1：

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

二、第一步：更新 Termux#

打开 Termux，执行：

1
pkg update

然后：

1
pkg upgrade -y

再安装 PRoot-Distro：

1
pkg install proot-distro -y

为什么要安装 PRoot-Distro？#

我们不直接把 Wrangler 装进 Android 的 Termux 环境，而是在 Termux 里面运行一个 Ubuntu 24.04 环境，再在 Ubuntu 里安装 Node.js 和 Wrangler。

这条路线更适合新手，也更容易处理 Wrangler 的 Linux/Node 原生依赖。

三、第二步：安装 Ubuntu 24.04#

执行：

1
proot-distro install ubuntu:24.04

等待安装完成。

如果看到类似：

1
[*] Installing Ubuntu (24.04)...

就耐心等它结束。

安装结束后，输入：

1
proot-distro list

你应该能看到已经安装好的 Ubuntu。

四、第三步：进入 Ubuntu#

执行：

1
proot-distro login ubuntu --shared-home

成功进入后，命令行通常会变成类似：

1
root@localhost:~#

这就说明：

你已经不是在 Android 的原生 Termux Shell 里，而是在 Termux 里的 Ubuntu 环境中了。

为什么使用 `--shared-home`？#

因为这样 Termux 和 Ubuntu 可以更方便地共享 Home 目录。

以后你在 Termux 的：

1
~/storage/downloads

里放 Worker 文件、数据库文件，进入 Ubuntu 后也能更方便地访问。

五、第四步：给 Termux 访问手机存储的权限#

如果你还没有执行过：

1
termux-setup-storage

建议现在退出 Ubuntu，回到原生 Termux：

1
exit

然后：

1
termux-setup-storage

Android 会弹出权限请求。

点击：

允许

之后手机的“下载”目录一般可以通过：

1
~/storage/downloads

访问。

例如：

1
手机：
2
Download/database.db

对应：

1
~/storage/downloads/database.db

再次进入 Ubuntu#

1
proot-distro login ubuntu --shared-home

六、第五步：更新 Ubuntu 并安装基础工具#

进入 Ubuntu 后执行：

1
apt update

然后：

1
apt upgrade -y

安装我们后面需要的工具：

1
apt install -y curl ca-certificates git sqlite3 unzip nano

这些工具分别用于：

工具	用途
`curl`	下载脚本、访问网络
`ca-certificates`	HTTPS 证书
`git`	获取项目代码
`sqlite3`	转换 SQLite 数据库
`unzip`	解压 ZIP
`nano`	编辑配置文件

七、第六步：安装 NVM#

先安装 NVM：

1
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

安装结束后：

1
source ~/.bashrc

检查：

1
nvm --version

如果出现类似：

1
0.40.3

就说明 NVM 已经安装成功。

如果版本号稍有不同，不需要和示例完全一致。

八、第七步：安装 Node.js 24#

安装 Node.js 24：

1
nvm install 24

启用：

1
nvm use 24

设为默认版本：

1
nvm alias default 24

检查 Node：

1
node -v

应该看到类似：

1
v24.x.x

再检查 npm：

1
npm -v

正常出现版本号即可。

九、第八步：安装 Wrangler#

建议不要把 Wrangler 随便全局安装，而是在一个专门的 Cloudflare 工作目录里面作为项目依赖使用。

创建目录：

1
mkdir -p ~/cloudflare

进入：

1
cd ~/cloudflare

初始化 npm 项目：

1
npm init -y

安装 Wrangler：

1
npm install --save-dev wrangler@latest

安装完成后检查：

1
npx wrangler --version

如果看到类似：

1
⛅ wrangler 4.x.x

就成功了。

Wrangler 版本会持续更新，所以版本号不一定和教程中的示例完全相同。

十、第九步：登录 Cloudflare#

执行：

1
npx wrangler login --device

Cloudflare 会给你一个网址和验证码。

一般会看到类似：

1
To authorize Wrangler, please visit:
2

3
https://dash.cloudflare.com/oauth2/device
4

5
and enter the code:
6

7
XXXXXXXX

接下来做什么？#

复制网址。
在手机浏览器打开。
登录你的 Cloudflare 账号。
输入 Termux 显示的验证码。
授权 Wrangler。
回到 Termux。

如果成功，会看到类似：

1
Successfully logged in.

十一、第十步：检查登录状态#

执行：

1
npx wrangler whoami

如果能正常显示 Cloudflare 账号信息，说明登录成功。

如果这里失败#

先不要继续操作。

常见原因包括：

没有完成浏览器授权
登录到了错误的 Cloudflare 账号
网络连接失败
Wrangler 没有正常安装

十二、第十一步：查看已有 D1#

因为你说 D1 已经创建过了，所以我们不要重新创建。

执行：

1
npx wrangler d1 list

你应该可以看到类似：

1
Name          UUID
2
my-database   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

记下：

1
D1 名称
2
D1 ID

例如：

1
D1 名称：
2
my-database
3

4
D1 ID：
5
12345678-1234-1234-1234-123456789abc

不要自己编数据库 ID，以 npx wrangler d1 list 显示的为准。

十三、第十二步：查看 D1 详细信息#

执行：

1
npx wrangler d1 info 你的D1名称

例如：

1
npx wrangler d1 info my-database

这一步可以帮助你确认数据库确实存在，以及 Wrangler 已经能够正常访问它。

十四、第十三步：获取已经创建好的 Worker#

你有两种情况。

情况 A：Worker 已经在 Cloudflare Dashboard 创建#

这是最方便的。

进入：

1
cd ~/cloudflare

然后执行：

1
npx wrangler init my-worker --from-dash 你的Worker名称

例如：

1
npx wrangler init my-worker --from-dash my-worker

Wrangler 会尝试把 Dashboard 里已经存在的 Worker 初始化到本地项目。

my-worker 是你本地项目目录的名字。
你的Worker名称 是 Cloudflare Dashboard 里面实际存在的 Worker 名字。

情况 B：你手里已经有 Worker 源代码#

例如你手里有：

1
my-worker/
2
├── package.json
3
├── wrangler.jsonc
4
├── src/
5
└── ...

那么不需要从 Dashboard 拉取，直接把整个项目放到：

1
~/cloudflare/

即可。

十五、第十四步：进入 Worker 项目#

假设本地项目叫：

1
my-worker

执行：

1
cd ~/cloudflare/my-worker

然后：

1
ls -la

正常情况下可能看到：

1
package.json
2
wrangler.jsonc
3
src

或者：

1
package.json
2
wrangler.toml
3
worker.js

不同项目结构可能不同。

十六、第十五步：检查 Wrangler 配置#

优先检查：

1
cat wrangler.jsonc

如果没有：

1
cat wrangler.toml

一个典型的 `wrangler.jsonc`#

例如：

1
{
2
  "$schema": "./node_modules/wrangler/config-schema.json",
3

4
  "name": "my-worker",
5

6
  "main": "src/index.js",
7

8
  "compatibility_date": "2026-10-02",
9

10
  "d1_databases": [
11
    {
12
      "binding": "DB",
13
      "database_name": "my-database",
14
      "database_id": "12345678-1234-1234-1234-123456789abc"
15
    }
16
  ]
17
}

这里最重要的是：

1
name
2
main
3
d1_databases

以及 D1 下面的：

1
binding
2
database_name
3
database_id

十七、第十六步：理解 D1 Binding#

这个概念非常重要。

例如 Wrangler 配置：

1
"d1_databases": [
2
  {
3
    "binding": "DB",
4
    "database_name": "my-database",
5
    "database_id": "12345678-1234-1234-1234-123456789abc"
6
  }
7
]

那么 Worker 代码里面通常会通过：

1
env.DB

访问这个 D1。

例如：

1
export default {
2
  async fetch(request, env) {
3
    const result = await env.DB
4
      .prepare("SELECT * FROM users")
5
      .all();
6

7
    return Response.json(result);
8
  }
9
};

这里：

1
DB

必须和配置里的：

1
"binding": "DB"

一致。

一个常见错误#

配置写：

1
"binding": "DB"

代码却写：

1
env.DATABASE

这样 Worker 就找不到对应的 D1 绑定。

所以：

先看原来的 Worker 代码，再决定 binding 叫什么。不要随便改。

十八、第十七步：备份现有 D1#

因为你的 D1 已经创建过了，所以在导入新的数据库之前，建议先备份。

例如：

1
npx wrangler d1 export my-database --remote --output=./d1-backup.sql

成功以后，你的项目目录里会多出：

1
d1-backup.sql

为什么要备份？#

假设你的 D1 原来已经存在：

1
users
2
settings
3
messages

而你的新 SQL 里又执行：

1
CREATE TABLE users ...

就有可能发生表已经存在、重复插入等问题。

先备份，至少还有恢复依据。

十九、第十八步：上传 SQL 数据库#

如果你的数据库文件已经是：

1
database.sql

把它放到 Worker 项目目录，例如：

1
~/cloudflare/my-worker/database.sql

然后：

1
cd ~/cloudflare/my-worker

执行：

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

例如：

1
npx wrangler d1 execute my-database --remote --file=./database.sql --yes

这条命令的意思：

1
操作 D1
2
↓
3
指定数据库
4
↓
5
操作远程 Cloudflare D1
6
↓
7
读取 database.sql
8
↓
9
执行里面的 SQL

二十、第十九步：如果手里的是 `.db` / `.sqlite` 文件#

这一步非常重要。

假设你拿到的是：

1
database.db

或者：

1
database.sqlite

不要直接把它作为 --file 上传。

因为 .db 是 SQLite 数据库文件本身，而 wrangler d1 execute --file 使用的是 SQL 文本。

第 1 步：进入数据库文件所在目录#

例如：

1
cd ~/cloudflare/my-worker

第 2 步：把 SQLite 导出成 SQL#

如果文件叫：

1
database.db

执行：

1
sqlite3 database.db ".dump" > database.sql

完成后检查：

1
ls -lh

应该能看到：

1
database.db
2
database.sql

第 3 步：检查 SQL 有没有正常生成#

执行：

1
head -n 30 database.sql

正常情况下可能看到：

1
PRAGMA foreign_keys=OFF;
2
BEGIN TRANSACTION;
3
CREATE TABLE ...
4
INSERT INTO ...

如果能看到这些 SQL 内容，就说明转换成功。

第 4 步：导入 D1#

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

例如：

1
npx wrangler d1 execute my-database --remote --file=./database.sql --yes

二十一、第二十步：检查 D1 数据#

数据库导入之后，建议马上检查表。

执行：

1
npx wrangler d1 execute 你的D1名称 --remote --command="SELECT name FROM sqlite_schema WHERE type='table' ORDER BY name;"

例如：

1
npx wrangler d1 execute my-database --remote --command="SELECT name FROM sqlite_schema WHERE type='table' ORDER BY name;"

如果导入成功，可能看到：

1
users
2
settings
3
messages

这样就说明：

D1 不只是“创建成功”，而是已经真正拥有数据库表。

再进一步查询某个表#

例如有：

1
users

可以：

1
npx wrangler d1 execute my-database --remote --command="SELECT * FROM users LIMIT 10;"

二十二、第二十一步：部署 Worker 前先测试#

进入 Worker 目录：

1
cd ~/cloudflare/my-worker

先运行：

1
npx wrangler deploy --dry-run

这个命令主要用于检查部署过程，而不会直接把 Worker 正式部署上线。

如果这里报错：

不要急着正式部署。

先把错误解决。

二十三、第二十二步：正式部署 Worker#

确认 --dry-run 没问题后：

1
npx wrangler deploy --keep-vars

推荐使用：

1
--keep-vars

因为你的 Worker 如果之前在 Cloudflare Dashboard 中设置过普通环境变量，部署时最好注意不要意外覆盖原来的变量。

部署成功以后，一般会看到 Worker 的 URL，例如：

1
https://my-worker.example.workers.dev

这就表示：

Worker 已经重新部署。

二十四、第二十三步：以后怎么更新 Worker#

以后就简单很多。

每次打开 Termux：

1
proot-distro login ubuntu --shared-home

进入项目：

1
cd ~/cloudflare/my-worker

然后先测试：

1
npx wrangler deploy --dry-run

确认无误后：

1
npx wrangler deploy --keep-vars

更新 D1 数据时#

如果新的数据已经是 SQL：

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

如果还是 SQLite：

1
sqlite3 database.db ".dump" > database.sql

然后：

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

二十五、常见问题#

1. `node: command not found`#

检查：

1
source ~/.bashrc

然后：

1
nvm use 24

再：

1
node -v

2. `nvm: command not found`#

执行：

1
source ~/.bashrc

然后检查：

1
nvm --version

如果还是不行，可以重新进入 Ubuntu：

1
exit

再：

1
proot-distro login ubuntu --shared-home

3. `wrangler: command not found`#

如果你是通过：

1
npm install --save-dev wrangler@latest

安装的，不要直接输入：

1
wrangler

而应该：

1
npx wrangler

例如：

1
npx wrangler --version

4. `npx wrangler login` 登录失败#

手机环境推荐：

1
npx wrangler login --device

不要优先折腾本地回调地址。

5. `d1 list` 看不到我的 D1#

先检查：

1
npx wrangler whoami

确认登录的是正确的 Cloudflare 账号。

然后：

1
npx wrangler d1 list

如果你的 D1 属于其他 Cloudflare 账号/账户，登录身份不对时自然看不到。

6. `table already exists`#

说明你的 D1 里已经存在这个表。

先备份：

1
npx wrangler d1 export 你的D1名称 --remote --output=./d1-backup.sql

不要直接乱删表。

如果你不清楚 SQL 文件到底会做什么，可以先打开：

1
nano database.sql

检查里面的：

1
CREATE TABLE
2
DROP TABLE
3
INSERT INTO

等语句。

7. `.db` 文件直接导入失败#

不要：

1
npx wrangler d1 execute xxx --remote --file=database.db

正确方法：

1
sqlite3 database.db ".dump" > database.sql

然后：

1
npx wrangler d1 execute xxx --remote --file=database.sql --yes

8. Worker 部署成功，但是网站还是不能用#

重点检查：

D1 binding#

配置：

1
"binding": "DB"

代码：

1
env.DB

两者是否一致。

数据库 ID#

检查：

1
database_id

是不是你真正的 D1 ID。

数据库名字#

检查：

1
database_name

是不是已经存在的 D1。

环境变量#

如果 Worker 原来在 Dashboard 配置了变量，部署时可以使用：

1
npx wrangler deploy --keep-vars

二十六、完整命令速查#

第一次安装#

Termux#

1
pkg update
2
pkg upgrade -y
3
pkg install proot-distro -y
4
termux-setup-storage
5
proot-distro install ubuntu:24.04
6
proot-distro login ubuntu --shared-home

Ubuntu#

1
apt update
2
apt upgrade -y
3
apt install -y curl ca-certificates git sqlite3 unzip nano

NVM#

1
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
2
source ~/.bashrc
3
nvm install 24
4
nvm use 24
5
nvm alias default 24

Wrangler#

1
mkdir -p ~/cloudflare
2
cd ~/cloudflare
3
npm init -y
4
npm install --save-dev wrangler@latest
5
npx wrangler --version

登录 Cloudflare#

1
npx wrangler login --device

检查账号#

1
npx wrangler whoami

查看 D1#

1
npx wrangler d1 list

查看 D1 信息#

1
npx wrangler d1 info 你的D1名称

获取已有 Worker#

1
cd ~/cloudflare
2
npx wrangler init my-worker --from-dash 你的Worker名称

备份 D1#

1
cd ~/cloudflare/my-worker
2
npx wrangler d1 export 你的D1名称 --remote --output=./d1-backup.sql

SQLite 转 SQL#

1
sqlite3 database.db ".dump" > database.sql

上传 SQL 到 D1#

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

检查表#

1
npx wrangler d1 execute 你的D1名称 --remote --command="SELECT name FROM sqlite_schema WHERE type='table' ORDER BY name;"

查询数据#

1
npx wrangler d1 execute 你的D1名称 --remote --command="SELECT * FROM users LIMIT 10;"

部署前检查#

1
npx wrangler deploy --dry-run

正式部署#

1
npx wrangler deploy --keep-vars

二十七、参考资料#

最后记住 4 条命令#

以后最常用的其实就这几个：

进入 Ubuntu#

1
proot-distro login ubuntu --shared-home

查看 Cloudflare 登录状态#

1
npx wrangler whoami

上传 D1 SQL#

1
npx wrangler d1 execute 你的D1名称 --remote --file=./database.sql --yes

部署 Worker#

1
npx wrangler deploy --keep-vars

建议第一次操作时严格按照本文顺序执行，不要跳步骤。
尤其是 D1：先确认数据库 → 再备份 → 再导入 → 再检查表 → 最后部署 Worker。

音乐

音乐

在 Termux 上配置 Cloudflare Wrangler，并上传已有 Worker 与 D1 数据库 | LegspCpd Blog - blog.legspcpd.top