godaddy-nodejs-hosting

GoDaddy Node.js Hosting

帮助用户构建或修复适用于 GoDaddy Node.js Hosting 的 Node.js 应用（上传 → 安装 → run build → run start）。包管理器：npm、pnpm 或 yarn（平台选择由锁文件决定）。

规则：contract.md。示例：examples.md。错误：troubleshooting.md。邮件：email.md。验证器：scripts/validate-paas.mjs。

选择使用哪种路径

用户意图	章节
新应用 / 搭建脚手架 / 从零开始	新应用工作流
现有代码库 / 部署失败 / 让应用适用于托管平台	改造现有应用
AI 导出（Lovable、Replit、Bolt 等）	改造现有应用 + AI 导出快速修复
使用 MySQL / 平台数据库	托管 MySQL
发送邮件 / 联系表单 / 通知	邮件

用户类型路由

非技术用户（不使用术语，例如“我在 Lovable 里做了这个应用”“怎么上传”）：

1. 先用通俗语言提供上传前检查清单。
2. 按照改造现有应用操作（现有 zip 或导出文件）。
3. 如果没有服务器，优先采用 静态 SPA + Express 或仅静态文件方案。对于使用 output: 'export' 的 Next.js，则改用 nextjs-static-export——说明：“你的应用会构建为静态文件。我们会添加一个小型服务器，让 GoDaddy 可以运行它——你的网站保持不变。”
4. 一次只做一项小改动；用通俗语言说明下一步托管操作（Git 同步或在界面中上传 zip）。
5. 在告知用户应用已就绪前，先运行验证器。

技术用户 - 现有应用：按照改造现有应用操作；仅使用匹配框架的 start/build 方案；不要重复解释基础知识。

技术用户 - 新应用：按照新应用工作流操作；使用框架检测中匹配框架的方案。

部署契约（摘要）

• 根目录中的 package.json，包含 name、version、main（对应文件必须存在）、scripts.build 和 scripts.start
• 如果没有内容需要编译，build 可以是 "echo build"；框架则需要实际的构建命令（见 examples.md）
• 在 process.env.PORT 上监听；框架需要主机地址时使用 0.0.0.0
• 运行时依赖放在 dependencies 中；不要上传 node_modules
• 使用 process.env 管理密钥；zip 中不要包含 .env；zip 小于 100 MB
• 每次上传一个应用；尽可能包含锁文件
• 仅允许出站 HTTP/HTTPS；如使用数据库，则通过 DB_* 环境变量和 mysql2 连接平台 MySQL（见 contract.md）
• 通过平台网关 (http://127.0.0.1:2525/api/email/send) 和提供的 sendEmail() 辅助函数发送邮件；不要使用 nodemailer，也不要使用外部 SMTP（见 email.md）

发布更新（与客户沟通）

平台支持在 Node.js Hosting 界面中同步 Git 仓库和上传 zip。有关 Agent 上下文，请参阅 AGENTS.md 中的 Deployment Flow。

• 不要根据 .git、锁文件或导出来源推断部署方式（zip 导出文件可能包含本地开发时生成的 .git）。
• **告知用户如何发布时，默认使用中性表述：**例如 “准备好后，可以在 Node.js Hosting 中通过 Git 同步或在托管界面中上传 zip 来更新应用。”
• 只有在用户说明或询问自己使用哪种方式时，才具体说明路径（zip 步骤或连接 / 推送 Git）。
• 未经用户确认，避免使用“上传新的 zip”或“推送到你的远程仓库”这类指向单一路径的措辞。

托管 MySQL

可选的平台 MySQL 会注入 DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD。应用必须从 process.env 读取每个变量（不得硬编码）。在 dependencies 中使用 mysql2，并使用参数化查询。

配置示例：examples.md#managed-mysql。验证器：检测到 DB 客户端或 Prisma MySQL provider 时触发 E009、E010。

电子邮件

应用通过平台内置网关 http://127.0.0.1:2525/api/email/send 发送事务性电子邮件（联系表单、通知、收据、密码重置）——该网关仅限环回访问，位于每个容器内部。无需 SMTP 配置、nodemailer 或第三方 API 密钥；容器无法路由出站 SMTP。

将 sendEmail() 助手复制到 src/server/email.ts，并从路由处理程序中调用它。所有电子邮件代码都必须调用该助手——不得直接向网关发送 POST 请求，也不得导入 nodemailer。

关键规则（完整详情：email.md）：

• 默认省略 from——网关会选用应用的规范发件人。仅当域名已验证时，才将 from 设置为硬编码字面值（未验证时 → 400）；绝不能使用用户输入。
• 固定收件人（联系表单管理员、提醒）从 process.env 获取（例如 CONTACT_FORM_RECIPIENT_EMAIL），并在 Node.js Hosting UI 中设置——绝不能硬编码，也不能使用 TODO 占位符。未设置时必须安全失败。每用户收件人应通过应用数据传入，而不是来自匿名请求正文。
• 不要向最终用户回显网关的原始错误——在服务器端记录日志，并显示通用失败消息。

配置示例和助手：email.md。契约规则：C13。迁移现有 nodemailer 代码：email.md#migrating-from-nodemailer。

适配现有应用

当用户已有项目（本地仓库、zip 导出文件，或在 Node.js Hosting 上运行失败的应用）时，请使用此路径。目标：仅确保兼容托管——不添加新功能、不进行重构，也不更改框架。

原则

• 不添加或删除产品功能；不重构无关代码。
• 尽量减少改动：优先调整 package.json（name、version、main、build、start）、监听／绑定代码行，并在缺少静态服务器文件时补上该文件——不要重写应用逻辑。
• 保留检测到的框架；仅根据该技术栈对应的 examples.md 调整 main、scripts.start 和 scripts.build。

适配工作流

根据 contract.md 检查（九项平台要求：package.json 字段、build/start、PORT、依赖、环境变量、Vite、zip 大小、网络、MySQL）。逐项检查是否符合要求，应用最小改动，并保留所有现有行为。

复制并跟踪进度：

- [ ] Run validator on project root (baseline)
- [ ] Map each error/warning to contract rule (see table below)
- [ ] Apply minimal fix per ID; use framework recipe for script names only
- [ ] Re-run validator until exit 0 (or document warnings if not --strict)
- [ ] install → build → start locally (match lockfile package manager)
- [ ] Pre-upload checklist complete

验证器（完成前必须运行）：

node scripts/validate-paas.mjs /path/to/project

从此技能目录运行（例如，在 npx skills add 后，或创建指向 ~/.cursor/skills/godaddy-nodejs-hosting 的符号链接后）。从 nodejs-hosting-agent-skill 克隆的仓库中运行：npm run validate -- /path/to/project。

症状详情：troubleshooting.md。

ID	常见的最小修复
E001	添加根目录下的 package.json
E002	按照对应方案添加或修复 scripts.start
E003	修复 start 入口路径，或添加缺失文件
E004	使用 process.env.PORT；移除硬编码的 listen(N)
E005	添加 scripts.build（echo build 或框架方案）
E006	将运行时依赖包移至 dependencies
E007	在 package.json 中添加 name 和 version
E008	添加指向现有入口文件的 main
W001	从上传内容中移除 .env；使用托管平台界面设置环境变量
W002	可选：添加 engines.node
W004	从部署内容（zip 或 Git）中排除 node_modules
E009	将 mysql2 添加到 dependencies
E010	从 process.env 读取每个 DB_*（参见 managed-mysql）
C14	创建 .npmrc，内容为 registry=https://registry.npmjs.org/。如果锁文件包含非公共 URL，请删除锁文件并重新安装

特殊情况

• Monorepo（C1）： 适配前，先提取出一个拥有独立根目录 package.json 的应用文件夹；除非用户提出要求，否则不要就地重构软件包。
• Next.js 静态导出： 应用标准 Next 方案前，检查 next.config.* 中是否设置了 output: 'export'。使用 nextjs-static-export（next build + Express 提供导出目录），不要使用 next start。根据配置匹配 distDir（默认为 out/）。采用与 Vite/Lovable 静态应用相同的托管模式，但构建命令为 next build。
• 仅前端／无服务端： 使用 vite-react-vue-spa 和 AI export quick fixes。
• 从其他托管平台迁移： 步骤相同；重点检查 PORT、start/build、dependencies 和锁文件。

对于 Replit、Lovable 和 Bolt 模式，在应用此工作流后，参见 AI export quick fixes。

按照与新应用相同的完成标准完成适配（验证器结果为 0、完成检查清单，并可在 Node.js Hosting 中更新）。

新应用工作流

复制并跟踪进度：

- [ ] Detect framework (package.json)
- [ ] Apply recipe from examples.md
- [ ] Add `.npmrc` with `registry=https://registry.npmjs.org/` to project root
- [ ] install && run build (if exists) && run start (npm, pnpm, or yarn — match user's lockfile)
- [ ] node scripts/validate-paas.mjs <project-dir>
- [ ] Pre-upload checklist complete

按照适配现有应用中的说明运行验证器。

框架检测

package.json 中的信号	方案
依赖项中包含 next（标准模式）	examples.md#nextjs — 先检查 next.config.*
next.config.* 中包含 output: 'export'	examples.md#nextjs-static-export
依赖项中包含 nuxt	examples.md#nuxtjs
@remix-run/node 或 remix	examples.md#remix
@nestjs/core	examples.md#nestjs
fastify	examples.md#fastify
vite（SPA）	examples.md#vite-react-vue-spa
react-scripts	examples.md#create-react-app
express、koa、hono 或纯 node 服务端	examples.md#express-koa-hono
仅前端／未知导出类型	examples.md#vite-react-vue-spa（静态服务端）

对于已知框架，不要自行编造 start 命令；请严格按照对应方案操作。

AI 导出快速修复

来源	修复方法
Replit	移除 .replit、replit.nix；确保根目录下有 start 脚本
Lovable / Bolt	添加用于提供 dist/ 或 build/ 静态文件的 Express 服务器；将 express 添加到 dependencies
Next.js 静态导出	在配置中设置 output: 'export'：保留 next build；添加 Express，以从 distDir（默认为 out/）提供导出目录（nextjs-static-export）——不要使用 Vite/Lovable 配方
缺少 package.json	创建包含 start 的文件；运行安装命令（npm/pnpm/yarn）以生成锁文件
端口硬编码	使用 process.env.PORT || 3000
依赖项放错部分	将运行时包移至 dependencies

对于 Lovable/Bolt 静态托管，请使用 vite-react-vue-spa 配方。

上传前检查清单

• package.json：name、version、main、build、start
• 生产依赖位于 dependencies 中；不要部署 node_modules（从 zip 或 Git 中排除）
• 使用 process.env.PORT 进行监听；通过 process.env 配置密钥
• 部署产物小于 100 MB（zip 上传）
• 可在本地运行：安装 → 构建 → 启动
• 项目根目录下有 .npmrc，内容为 registry=https://registry.npmjs.org/。锁文件中的 URL 必须指向公共 npm（如果不是，请重新生成锁文件）
• 存在锁文件（已提交或包含在上传文件中）；验证器退出代码为 0；没有 .env
• 仅允许 HTTP/HTTPS 出站；如适用，数据库使用 DB_* + mysql2

完成标准

只有满足以下条件，任务才算完成：

1. validate-paas.mjs 在项目目录中退出代码为 0。
2. 满足上传前检查清单。
3. 用户知道可以在 Node.js Hosting 中发布/更新应用（在 UI 中通过 Git 同步或 zip 上传）。如果用户已经说明使用哪种方式，则只提及该方式。