测试文章1
第一篇测试

W3C Cool Nuxt 环境搭建与 EdgeOne 部署笔记
记录日期:2026-11-16 项目:
image-workspaces-w3c(Nuxt 4 复刻public.w3c.cool) 目标:在容器内跑通本地开发,并评估 EdgeOne 边缘函数 + Nuxt 站部署路径
一、环境概况
| 项 | 值 |
|---|---|
| 基础镜像 | node:24-slim(Debian 12 bookworm) |
| Node | v24.22.3 |
| pnpm | 12.21.0 |
| 项目框架 | Nuxt 4.6.4 + @nuxt/ui 4.12.0 + Tailwind 4.3.5 |
| 数据层 | node:sqlite(DatabaseSync) |
| 认证 | 自签 HS256 JWT(admin_token cookie) |
镜像内已预装:code-server 4.145.2、5 个 VS Code 扩展(yaml / eslint / gitlens / volar / coding-copilot)、coscli、pnpm edgeone pagefind wrangler typescript @biomejs/biome。
二、依赖安装与 pnpm 12 的构建脚本拦截
现象
执行 pnpm install 后,包全部装好(643 个),但末尾报错:
Error: ERR_PNPM_IGNORED_BUILDS
× installing dependencies
╰─▶ Ignored build scripts: esbuild@0.27.7, esbuild@0.28.2, vue-demi@0.14.10
help: Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.
原因
pnpm 10+ 默认不自动执行依赖的 postinstall 等构建脚本(防供应链攻击)。pnpm 12 中若有脚本被忽略,会直接以 ERR_PNPM_IGNORED_BUILDS 终止安装流程。
涉及的包:
esbuild(两个版本):postinstall负责下载/校验平台二进制,缺了会导致后续构建找不到二进制。vue-demi:Vue 2/3 适配脚本。
解决
pnpm approve-builds
# 交互界面中空格选中 esbuild、vue-demi,回车确认
pnpm 会记录批准结果并执行对应 postinstall:
esbuild@0.28.2: Running postinstall script, done in 46ms
esbuild@0.27.7: Running postinstall script, done in 46ms
vue-demi@0.14.10: Running postinstall script, done in 73ms
再次 pnpm install:
✓ Lockfile passes supply-chain policies
. postinstall$ nuxt prepare
│ ℹ Nuxt Icon server bundle mode is set to local
│ ◆ Types generated in .nuxt.
Done in 956ms using pnpm v12.21.0
环境就绪。
备选方案(不推荐):
PNPM_CONFIG_STRICT_DEP_BUILDS=false pnpm install可绕过检查,但 esbuild 等脚本仍不会执行,后续构建大概率报错。
三、本地开发
pnpm dev # http://localhost:3000
- 后台入口:
/admin/login,默认密码123 - 数据:首次启动自动在
.data/w3c.db建库并灌种子数据 - 重置数据:删除
.data/后重启 - 其他命令:
pnpm build/pnpm preview/pnpm generate/pnpm typecheck
四、EdgeOne 部署路径评估
4.1 核心冲突:node:sqlite 与 Edge Runtime
EdgeOne 的 Functions 分两类:
| 类型 | 运行时 | node:sqlite 可用性 |
|---|---|---|
| Edge Functions | V8 隔离环境(Edge Runtime) | ❌ 不支持 Node 内置模块与 npm require |
| Cloud Functions | Node.js / Python / Go | ✅ Node.js 环境理论可用 |
项目的 server/utils/db.ts 依赖 node:sqlite,无法直接跑在 Edge Functions 上。README 本身已预见此问题:
若部署到 EdgeOne 这类边缘运行时且不支持
node:sqlite,替换server/utils/db.ts为 KV / D1 实现即可,上层 API 保持不变。
4.2 推荐架构
用户请求
│
▼
EdgeOne 边缘节点
│
├─ Edge Functions(纯 JS)── 轻量逻辑:鉴权前置、重定向、Header 改写、缓存控制
│
▼
Nuxt 应用(EdgeOne Makers 托管,走 Cloud Functions/Node.js 路径)
│
├─ 前台 SSR / SSG,后台 htmx 片段端点,API 路由
└─ 数据层:node:sqlite → 外部存储(视运行时而定)
htmx 后台的“返回 HTML 片段”模式在架构上适合 EdgeOne(短时 HTTP 请求,不涉及流式传输)。Makers 对 Nuxt 3.16+ / Nuxt 4 支持 SSR、SSG、ISR/SWR、中间件,但流式传输与 @nuxt/image 优化暂不支持。
4.3 改造清单
-
数据层替换(必须)
- 若 Makers 的 Cloud Functions 确认支持 Node.js:可保留
node:sqlite,但需验证.data/w3c.db路径可写与持久化。 - 若必须走 Edge Runtime:换成外部数据库(Turso/libSQL、PostgreSQL)或 EdgeOne KV/Blob;关系型查询(状态过滤、排序)用 KV 不理想。
- 最省事起步:种子数据抽成静态 JSON,API 只读,先跑通 UI 与部署链路。
- 若 Makers 的 Cloud Functions 确认支持 Node.js:可保留
-
认证机制
server/middleware/admin-auth.ts用node:crypto的 HMAC-SHA256。- 若中间件运行在 Edge 环境,需改写为 Web Crypto API(
crypto.subtle.sign)。 - 若运行在 Nitro 的 Node.js 服务端,则无需改动。
-
htmx 4.0.1
- 自托管在
public/4.0.1.min.js,静态资源部署不受影响。 - 注意 Makers 不支持流式传输,若交互依赖 SSE/长轮询需确认。
- 自托管在
-
@nuxt/ui+ Tailwind v4- 纯前端资源,部署无影响。未使用
@nuxt/image则无兼容问题。
- 纯前端资源,部署无影响。未使用
-
部署命令
- 要求 EdgeOne CLI ≥ 1.2.4,
edgeone makers deploy。 - Makers 构建自动检测包管理器(支持 pnpm 6–9),本项目统一用 pnpm。
- 要求 EdgeOne CLI ≥ 1.2.4,
4.4 验证顺序(建议)
- 本地
pnpm dev跑通前台与后台全部路由及 htmx 交互。 pnpm build确认.output/正常生成。- EdgeOne 控制台建 Makers 项目,先推最小 Nuxt 应用,确认构建环境是否支持
node:sqlite。 - 若报错,按 4.3 抽象数据层(静态 JSON / 外部存储顶替),再逐步接真实数据库。
五、关键结论
- Nuxt 站走 EdgeOne Makers(Pages)托管,支持 SSR/ISR;边缘函数作为独立
edge-functions/目录的纯 JS 轻量逻辑层,两者同项目共存、运行在不同层。 - 不要试图把 Nuxt SSR 塞进 Edge Functions(仅 JS、CPU 200ms、内存 128MB、包 ≤5MB)。
- 项目当前的
node:sqlite是部署到 EdgeOne 的最大不确定点,优先在 Makers 上做最小验证,再决定数据层方案。 - 环境侧无需额外安装 Go;Node 24 + pnpm +
edgeoneCLI 已满足 Nuxt 站开发与部署需求。
附:常用命令速查
# 依赖
pnpm install
pnpm approve-builds # 批准被拦截的构建脚本
# 开发
pnpm dev # http://localhost:3000,后台 /admin/login(密码 123)
pnpm build # Nitro 输出 .output/
pnpm preview
pnpm typecheck
# 数据重置
rm -rf .data/ # 删库后重启自动重建 + 灌种子数据
# EdgeOne
edgeone login
edgeone makers link
edgeone makers dev
edgeone makers deploy -n <项目名>
评论 0
发表评论