企业官网建设流程全解析

如何快速上手eSIM-Tools开发：本地调试、测试与构建的完整开发者指南

【免费下载链接】eSIM-Tools专为已有 Giffgaff 和 Simyo 号码的用户设计的现代化 eSIM 管理工具集，支持将物理 SIM 卡转换为 eSIM、设备更换和二维码生成。(A modern set of eSIM management tools designed specifically for users who already have Giffgaff and Simyo numbers, offering support for converting physical SIM cards to eSIMs, device replacements, and QR code generation.)项目地址: https://gitcode.com/gh_mirrors/es/eSIM-Tools

eSIM-Tools 是一个专为 Giffgaff 和 Simyo 用户设计的免费 eSIM 管理工具集，支持物理 SIM 卡转 eSIM、设备更换和二维码生成。本文面向首次参与开发的你，用一份完整的开发者指南串起本地调试、Jest 测试与构建部署三大环节，10 分钟即可在本地跑通整个项目。

🧭 先读懂项目：技术栈与目录结构

在动手之前，先花 1 分钟了解 eSIM-Tools 的架构，这能帮你快速定位代码：

核心目录速查：

• Giffgaff 前端：src/giffgaff/ — OAuth/MFA/GraphQL 完整流程
• Simyo 前端：src/simyo/ — 登录、设备更换、eSIM 激活
• 通用工具模块：src/js/modules/ — 日志、安全存储、i18n 等可复用模块
• Serverless 后端：netlify/functions/ 与 netlify/edge-functions/
• 构建脚本：scripts/ — 质量检查、安全扫描、部署准备
• 测试：tests/ — 按模块划分（modules / giffgaff / simyo / security）

🚀 一键安装：环境要求与依赖配置

环境要求（见 package.json 的engines字段）：

• Node.js ≥ 18.0.0
• npm ≥ 8.0.0

三步完成初始化：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/es/eSIM-Tools cd eSIM-Tools # 2. 安装依赖 npm install # 3. 配置环境变量 cp env.example .env

💡ACCESS_KEY是必填项（Functions 访问密钥），可用openssl rand -hex 32生成强随机密钥。完整变量说明见 env.example 中的注释。

🖥️ 本地调试：两种开发服务器模式

项目提供了两种本地调试方式，按需选择：

npm run dev # Express 服务器 + nodemon 热重载 (localhost:3000) npm run netlify-dev # Netlify Dev 完整模拟 (localhost:8888)

• npm run dev：由 server.js 启动的 Express 开发服务器，自动提供静态文件服务和 API 代理（解决 CORS 问题），修改代码后 nodemon 会自动重启。注意predev钩子会先执行npm run build，所以首次启动会稍慢。
• npm run netlify-dev：完整模拟线上 Netlify 环境，Functions、Edge Functions 与重定向规则全部生效，联调后端接口时推荐使用这种方式。

调试 Giffgaff 流程时，可以对照官方图文教程 docs/User_Guide.md 逐步复现用户视角的操作：

修改 Giffgaff 前端模块时，入口在 src/giffgaff/giffgaff_modular.html：

Simyo 流程入口在 src/simyo/simyo_modular.html：

🧪 测试流程：Jest 单元测试三连命令

项目使用 Jest 30 + jsdom 环境，配置集中在 jest.config.js（含覆盖率阈值与 CSS/图片 mock 映射）。测试文件统一放在 tests/ 下，按模块分子目录组织。

npm test # 运行全部测试 npm run test:watch # 监听模式，改代码自动重跑 npm run test:coverage # 生成覆盖率报告（text/html/lcov）

几个实用技巧：

• 只跑单个测试文件：npx jest tests/modules/utils.test.js
• 新测试文件匹配**/tests/**/*.test.js即可被自动发现，无需改配置
• 静态资源（css/png 等）已通过 tests/mocks/ 中的styleMock.js、fileMock.js自动 mock，写测试时无需处理

⚠️ 提交前务必运行npm test确认全部通过，pre-push 钩子也会执行完整检查。

📦 构建流程：从源码到 dist 产物

npm run build # 静态资源拷贝 + esbuild 转译输出到 dist/ npm run check:links # 生产 HTML 本地资源脱链检查（生产零脱链）

构建入口是 scripts/build-static.js，它负责把 index.html 及静态资源复制到dist/，再用 esbuild 按 browserslist 配置转译 JS。路由与重定向规则（如/giffgaff→ 模块化页面、/bff/*→ Edge Function）全部定义在 netlify.toml 中。

质量与安全门禁（部署前必跑）：

npm run quality-check # 14 项代码质量检查（含脱链检查） npm run security-check # 安全配置扫描 npm run deploy-prepare # 一键组合：质量 + 安全 + 构建

Git Hooks 已内置自动化把关：scripts/pre-commit-check.js 在提交前检查、scripts/pre-push-check.js 在推送前执行完整检查，可用npm run hooks:install启用。

🚀 部署与验证

npm run deploy-test # 本地验证 Netlify 配置 npm run deploy # 构建并部署到 Netlify 生产环境

部署流程为：本地开发 → 构建静态资源 → 部署到 Netlify，构建命令与发布目录均由 netlify.toml 的[build]段统一管理（dist/目录 +netlify/functions+netlify/edge-functions）。

🧰 常见问题速查

💡 更多踩坑记录与架构决策，可查阅根目录 CLAUDE.md 与 tests/CLAUDE.md 中的文档索引。

📌 小结

至此你已经完整走通了 eSIM-Tools 的开发闭环：克隆安装 → 配置环境变量 → 双模式本地调试 → Jest 测试 → 构建与质量门禁 → 部署验证。项目坚持"无框架原生 JS + Serverless + 原生 ES6 模块"的设计，代码路径清晰、依赖极轻，非常适合新手从通用工具模块（src/js/modules/）或测试用例（tests/modules/）入手贡献你的第一个 PR。祝开发顺利！🎉

【免费下载链接】eSIM-Tools专为已有 Giffgaff 和 Simyo 号码的用户设计的现代化 eSIM 管理工具集，支持将物理 SIM 卡转换为 eSIM、设备更换和二维码生成。(A modern set of eSIM management tools designed specifically for users who already have Giffgaff and Simyo numbers, offering support for converting physical SIM cards to eSIMs, device replacements, and QR code generation.)项目地址: https://gitcode.com/gh_mirrors/es/eSIM-Tools