运行 是做什么的?
一个站点只有在实际运行过之后才算完成。源代码告诉你的是作者的意图;而浏览器展示的是用户得到的最终效果。这个技能是从文件夹到渲染页面的最短路径。
运行它
node <skill 文件夹>/scripts/serve.mjs <目录> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detect仅打印检测结果而不启动任何服务。当文件夹不熟悉时,先执行此操作。--port从指定端口开始查找,并使用下一个空闲端口,因此两个项目可以同时运行。--open打开默认浏览器。--shot out.png通过 Playwright 在 1440px 宽度下渲染页面,并截取整个页面高度的截图。--stop根据.run/state.json终止进程树。
它会在项目旁边写入 .run/state.json(包含 pid、port、url、command)和 .run/server.log。这两个文件是启动和停止之间交接的全部内容。
它检测的内容
| 找到的文件 | 执行的操作 |
|---|---|
包含 dev、start、serve 或 preview 脚本的 package.json | 在空闲端口上运行 npm run <对应脚本>,并设置 PORT 环境变量 |
根目录下的 index.html | 在该文件夹上运行 python -m http.server |
public/index.html、dist/index.html、build/index.html | 以构建输出目录为根目录启动静态服务器 |
| 存在配置文件但没有脚本 | 报告并停止:该项目需要使用自己的命令 |
go.mod、Cargo.toml、pubspec.yaml | 报告并停止:请使用项目自身的运行命令 |
关于框架细节、端口默认值和需要了解的失败模式,请参阅 references/stacks.md。
结果的解读
该脚本只验证三件事:进程已启动、端口已响应、页面已渲染。但它无法告诉你:
- 在 375、768 和 1440 宽度下布局是否正确(请使用
sitecraft/scripts/verify.mjs来验证) - 控制台是否干净(此处不捕获控制台信息;
verify.mjs会捕获) - 截图中的页面是否就是用户想要的页面(请检查 URL 是否与您请求的路由一致)
因此循环是:serve.mjs --shot,用肉眼查看截图,修复,再次截图。一次操作最多进行三次渲染;超过这个次数,问题就不在于 CSS,而在于方案本身。
规则
- 永远不要留下一个持续运行的服务器。 检查完成后停止它,或者明确说明它仍在运行及其端口。用户的机器上残留开发服务器会带来混乱。
- 不要启动你无法停止的服务。 如果项目需要 Docker、数据库或付费 API 密钥,请先说明再启动任何东西。
- 报告真实的 URL。 例如
localhost:4173,而不是“这个应用”。如果由于 4173 被占用而端口发生变更,请告知新的端口。 - 在猜测之前先读取日志。 启动失败几乎总是由于缺少依赖、缺少环境变量或端口已被占用。
.run/server.log包含了答案,引用实际错误比猜测更有效。 - 未经告知不要进行安装。 如果缺少
node_modules,通常npm install是正确的做法,但这也修改了用户的项目。执行后需说明已运行,或者当安装量较大时征得同意。 - 优先使用静态服务器而非框架服务器。 当构建输出存在且是最新的时,提供
dist/目录比运行开发服务器更快、更准确。
当它无法启动时
- 读取
.run/server.log并引用第一个真正的错误,而不是最后一行。 - 缺少依赖:在项目中运行
npm install,然后重试。 - 缺少环境变量:查找
.env.example,说明需要哪些变量,如果缺少敏感值则停止。 - 端口已被占用:脚本会自动跳到下一个空闲端口;如果仍然失败,通常是因为框架配置中硬编码了端口。
- 需要构建步骤:先运行
npm run build,然后提供dist/目录。 - 原生或容器化应用:请使用项目文档中指定的命令。并非所有技术栈都适合用脚本处理。
检查清单
- 检测技术栈而非猜测
- 启动服务并看到真实的 HTTP 响应,而不仅仅是进程已生成
- 报告确切的 URL 和端口
- 查看了截图,而不仅仅是日志
- 检查路由是否与预期的页面一致
- 停止服务,或说明它仍在运行及其位置
- 失败时引用了真正的错误信息