Nuxt3 项目适配 Cloudflare Pages 跨平台部署全记录
个人网站域名（在 Space 买的，转入 Cloudflare 管理）搭配 GitHub + Cloudflare Pages 实现自动化部署——本地修改代码，push 到 GitHub，Cloudflare 自动拉取构建上线。。
这篇文章完整记录了从 Windows 本地开发环境到 Cloudflare Pages（Linux 构建环境）的适配全过程
一、冲突根源
本地 Windows 系统下载的依赖二进制包（oxc、esbuild 等）是 Windows 平台专属，而 Cloudflare Pages 云端构建服务器为 Linux 系统。直接推送代码会出现跨平台二进制文件报错，构建失败。
说白了：Windows 装的依赖，Linux 不认。
二、本地 Windows 端清理适配步骤
1. 停止本地开发服务
关闭 npm run dev 运行中的项目，避免文件占用。
2. 清除平台锁定依赖
删除项目根目录两处文件：
node_modules完整文件夹- 锁文件
package-lock.json/yarn.lock
3. 重装跨平台通用依赖
npm install
重新生成适配 Linux 的 lock 文件，这次不会再绑定 Windows 专属二进制程序。
4. 本地验证打包
npm run generate
根目录正常生成 dist 文件夹，代表打包逻辑无问题。
5. Git 过滤依赖
确认 .gitignore 文件包含 node_modules/，禁止上传超大依赖文件夹至仓库。
6. 推送代码
将修改后的源码提交、push 到 Gitee/GitHub 远程仓库。
三、Cloudflare Pages 云端 Linux 环境配置
1. 添加环境变量解决跨平台编译
进入 Pages 项目面板 → 设置 → 环境变量，新增变量：
变量名：NODE_ENV 值：production
变量名：NODE_VERSION 值：20
变量名：NPM_CONFIG_CI 值：false
变量名：npm_config_oxc_platform 值：linux
强制云端使用 Linux 版本编译工具，这是解决 oxc 等二进制包跨平台报错的关键。
2. 核对构建命令
Nuxt SSG 静态打包固定构建指令：
| 配置项 | 值 |
|---|---|
| 安装命令 | npm install |
| 构建命令 | npm run generate |
| 输出目录 | dist |
3. 清理旧失败部署记录
删除历史构建记录，触发全新完整构建，避免旧缓存干扰。
四、两种部署方案对比
方案一：Git 自动构建（推荐）
完成本地清理 + 云端环境变量配置后，每次 Windows 本地改代码 push 仓库，Linux 云端自动重新打包、部署。
方案二：手动拖放 dist 文件夹
若自动构建持续报错，本地 Windows 执行 npm run generate 生成 dist，直接手动上传至 Cloudflare Pages，绕过 Linux 云端构建步骤。
优点是无跨平台冲突，缺点是每次修改需要手动上传文件。