测试分类

测试文章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 改造清单

  1. 数据层替换(必须)

    • 若 Makers 的 Cloud Functions 确认支持 Node.js:可保留 node:sqlite,但需验证 .data/w3c.db 路径可写与持久化。
    • 若必须走 Edge Runtime:换成外部数据库(Turso/libSQL、PostgreSQL)或 EdgeOne KV/Blob;关系型查询(状态过滤、排序)用 KV 不理想。
    • 最省事起步:种子数据抽成静态 JSON,API 只读,先跑通 UI 与部署链路。
  2. 认证机制

    • server/middleware/admin-auth.ts 用 node:crypto 的 HMAC-SHA256。
    • 若中间件运行在 Edge 环境,需改写为 Web Crypto API(crypto.subtle.sign)。
    • 若运行在 Nitro 的 Node.js 服务端,则无需改动。
  3. htmx 4.0.1

    • 自托管在 public/4.0.1.min.js,静态资源部署不受影响。
    • 注意 Makers 不支持流式传输,若交互依赖 SSE/长轮询需确认。
  4. @nuxt/ui + Tailwind v4

    • 纯前端资源,部署无影响。未使用 @nuxt/image 则无兼容问题。
  5. 部署命令

    • 要求 EdgeOne CLI ≥ 1.2.4,edgeone makers deploy。
    • Makers 构建自动检测包管理器(支持 pnpm 6–9),本项目统一用 pnpm。

4.4 验证顺序(建议)

  1. 本地 pnpm dev 跑通前台与后台全部路由及 htmx 交互。
  2. pnpm build 确认 .output/ 正常生成。
  3. EdgeOne 控制台建 Makers 项目,先推最小 Nuxt 应用,确认构建环境是否支持 node:sqlite。
  4. 若报错,按 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 + edgeone CLI 已满足 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

  • 还没有评论,来抢沙发。

发表评论

正文图片

© 2026 W3C