XiaoDaiGua-Ray d489235be0
build(pages): deploy through GitHub Actions artifacts
Use Ubuntu 24.04 and Node 24 Pages actions for builds from main.
2026-11-06 23:50:04 +08:00

42 lines
4.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 工程检查与部署
## 常用命令
| 命令 | 用途 |
| -------------------------------- | -------------------------------------------------------------- |
| `pnpm env:check` | 校验 Node、pnpm 与依赖安装 |
| `pnpm dev` | 同步图标清单并启动 Vite |
| `pnpm harness context` | 查任务域;追加 `routing`、`table-pro`、`docs` 等查看实现与验证 |
| `pnpm harness verify table-pro` | 按域运行定向测试或项目检查 |
| `pnpm harness verify all` | 集成风险或发布时运行全量检查并生成本地报告 |
| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 |
| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 |
| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 |
| `pnpm packages:check` | 检查公开入口、依赖声明和循环依赖 |
| `pnpm pages:build` | 将后台与文档组装到 `dist/pages` |
| `pnpm docs:dev` | 启动文档开发站 |
| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 |
| `pnpm docs:preview` | 预览已构建的文档站 |
日常修改先运行相关测试文件或 `pnpm harness verify <scope>`,再根据改动补充格式、ESLint 和类型检查。纯措辞、注释或维护文档修正可只检查内容和格式;索引变化加 `pnpm harness check`。依赖、公共导出、构建配置等集成风险、发布或明确要求时,才在任务收尾运行一次全量检查。Pages 发布独立运行构建,本地全量检查入口仍为 `pnpm check`。
全量检查包含环境、Harness、API 与包边界、图标同步、类型、ESLint、Prettier、Vitest,以及后台和文档构建。`pnpm harness verify` 省略 scope 时仍执行全量,日常使用应显式指定 scope。Harness 在 `.harness-local/runs/` 写命令结果,所有命令均不启动浏览器。
浏览器验收按影响范围单独记录:交互变化只操作对应页面,布局变化增加桌面和窄屏,颜色变化增加明暗主题,文案或国际化变化核对中英文。共享能力选择有差异的代表调用方;纯逻辑、维护文档和读者文档纯措辞修正无需浏览器。检查通过后,只重跑受后续修改影响的部分,无需遍历页面、语言、主题和视口的所有组合。
## 部署到子路径
`pnpm build` 输出 `dist/production`。将产物部署到与 `vite.custom.config.ts` 中 `base` 对应的路径。默认应用为 `/ray-template/`,域名根目录部署改为 `/`。Vite 默认打包本地依赖;可选 CDN 模式需另外确认目标环境能访问 CDN。
组合部署使用 `pnpm pages:build`,将 `dist/pages` 作为同一个站点的产物。官方地址为 `/ray-template/`,其下 `docs/` 目录提供 v6 官网。Pages 工作流在 `main` 每次 push 后于 Ubuntu 24.04 构建,通过 GitHub Pages 制品部署,也支持在 `main` 手动发布。构建时传入 `RAY_TEMPLATE_SOURCE_REF`,把文档的当前源码链接固定到发布提交。使用此工作流前,在仓库 **Settings → Pages → Source** 选择 **GitHub Actions**,并确认 `github-pages` 部署环境允许 `main`。
公开生产部署可在构建环境设置 `RAY_TEMPLATE_SITE_ORIGIN` 为实际站点源地址(例如 `https://example.com`),由 base 补足路径。未配置时应用产物使用 `noindex`。公开 sitemap 列出入口页,登录后的 hash 路由用于应用交互。
## 二次开发约定
- 新页面遵循 Vue 3 Composition API + TSX 或现有 SFC 模式。复用现有组件,声明按职责归档。
- Vue、Router、Pinia 的自动导入声明由生成器维护;类型使用 `import type`。应用、测试、Node 配置的 TS 边界不同。
- 格式由 Prettier 管理,ESLint 使用 flat config。提交约定和注释写法以应用仓库当前规则为准。
[工程与部署入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/docs/architecture.md) · [AI Harness](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/harness/README.md) · [注释规范](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/docs/comment-style.md)