Fix/azure static web apps deployment #2
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Change: 修复 Azure Static Web Apps 部署配置 | ||
|
|
||
| ## Why | ||
|
|
||
| 当前 Azure Static Web Apps 部署工作流配置存在多个问题导致部署失败： | ||
| 1. `output_location` 设置为 `"build"`，但项目实际构建输出目录为 `"dist"`（与 Vite 配置一致） | ||
| 2. 使用过时的 `actions/checkout@v3`，而项目其他工作流已使用 `v4` | ||
| 3. OIDC 认证依赖使用了旧版本的 `@actions/core@1.6.0` | ||
| 4. 缺少明确的 Node.js 版本配置和构建步骤 | ||
| 5. 未使用 `skip_app_build: true` 导致 Azure 尝试重复构建 | ||
|
|
||
| 参考项目 `pcode-docs` 已有经过验证的 Azure Static Web Apps 部署配置，采用明确的手动构建流程和正确的路径配置。 | ||
|
|
||
| ## What Changes | ||
|
|
||
| - **修复 output_location 配置**：从 `"build"` 更改为 `"dist"`，并设置 `app_location: "dist"` + `skip_app_build: true` | ||
| - **统一 GitHub Actions 版本**：将 `actions/checkout` 升级到 `@v4` | ||
| - **添加显式构建步骤**：在工作流中明确添加 Node.js 设置、依赖安装和构建步骤 | ||
| - **添加 Azure Static Web Apps 配置文件**：创建 `public/staticwebapp.config.json` 以支持 React Router 客户端路由 | ||
| - **优化工作流结构**：参考 `pcode-docs` 项目，添加环境变量和更清晰的配置 | ||
| - **改进错误处理**：添加 `verbose: true` 以便调试部署问题 | ||
|
|
||
| **注意**：此修复不影响现有的 GitHub Pages 部署流程（`deploy.yml`）。 | ||
|
|
||
| ## Impact | ||
|
|
||
| - **Affected specs**: `deployment` | ||
| - **Affected code**: | ||
| - `.github/workflows/azure-static-web-apps-ambitious-moss-03f17d600.yml` (完全重构) | ||
| - `public/staticwebapp.config.json` (新建，用于 SPA 路由支持) | ||
| - **Benefits**: | ||
| - Azure Static Web Apps 部署将成功完成 | ||
| - 应用将在 Azure Static Web Apps 环境中可访问 | ||
| - React Router 客户端路由正常工作（通过 staticwebapp.config.json） | ||
| - 工作流配置更加健壮、安全和易于调试 | ||
| - 与项目其他工作流的依赖版本保持一致 | ||
| - **Risks**: 低风险 - 主要是配置修复，不涉及应用代码变更 | ||
| - **Testing**: 通过 PR 部署预览验证修复效果，确认后在 main 分支生效 | ||
|
|
||
| ## Status | ||
|
|
||
| **Status**: ExecutionCompleted | ||
| **Executed By**: Claude Sonnet 4.5 | ||
| **Execution Date**: 2025-02-05 | ||
| **Branch**: fix/azure-static-web-apps-deployment | ||
| **Commit**: 950f55c | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Azure Static Web Apps 自动部署 | ||
|
|
||
| 系统 SHALL 支持通过 GitHub Actions 实现代码推送后的自动构建和部署到 Azure Static Web Apps。 | ||
|
|
||
| #### Scenario: 代码推送触发自动部署 | ||
| - **WHEN** 用户将代码推送到 main 分支或创建 Pull Request | ||
| - **THEN** GitHub Actions 自动触发构建流程 | ||
| - **AND** 执行显式的 Node.js 环境设置和依赖安装 | ||
| - **AND** 执行 Vite 生产构建生成 `dist/` 目录 | ||
| - **AND** 构建成功后自动部署到 Azure Static Web Apps | ||
| - **AND** 提供部署状态反馈 | ||
|
|
||
| #### Scenario: Pull Request 预览部署 | ||
| - **WHEN** 用户创建或更新 Pull Request | ||
| - **THEN** GitHub Actions 触发预览环境构建和部署 | ||
| - **AND** 生成唯一的预览环境 URL | ||
| - **AND** 在 PR 中显示部署状态和预览链接 | ||
|
|
||
| #### Scenario: 部署失败通知 | ||
| - **WHEN** 部署过程中发生错误 | ||
| - **THEN** GitHub Actions 显示失败状态 | ||
| - **AND** 启用详细日志模式 (`verbose: true`) 提供错误详情 | ||
| - **AND** 提供错误日志和调试信息 | ||
|
|
||
| #### Scenario: 手动构建流程 | ||
| - **WHEN** Azure Static Web Apps 工作流执行 | ||
| - **THEN** 使用 `skip_app_build: true` 跳过 Azure 平台自动构建 | ||
| - **AND** 工作流显式执行 `npm ci` 和 `npm run build` | ||
| - **AND** 将 `app_location` 指向构建输出目录 `dist/` | ||
| - **AND** 确保部署的是最新构建产物 | ||
|
|
||
| #### Scenario: SPA 客户端路由支持 | ||
| - **WHEN** 应用部署到 Azure Static Web Apps | ||
| - **THEN** 系统包含 `public/staticwebapp.config.json` 配置文件 | ||
| - **AND** 配置文件设置 `navigationFallback.rewrite` 为 `"index.html"` | ||
| - **AND** 构建流程将配置文件复制到 `dist/staticwebapp.config.json` | ||
| - **AND** 用户直接访问任何路径（如 `/generator`）时返回 `index.html` | ||
| - **AND** React Router 正确处理客户端路由导航 | ||
|
|
||
| ## MODIFIED Requirements | ||
|
|
||
| ### Requirement: 构建配置优化 | ||
|
|
||
| 系统 SHALL 优化生产环境构建配置，确保构建产物符合多平台部署要求（GitHub Pages 和 Azure Static Web Apps）。 | ||
|
|
||
| #### Scenario: 构建输出目录统一 | ||
| - **WHEN** 执行生产构建（`npm run build`） | ||
| - **THEN** Vite 配置将输出目录设置为 `dist/` | ||
| - **AND** GitHub Pages 工作流从 `dist/` 读取构建产物 | ||
| - **AND** Azure Static Web Apps 工作流从 `dist/` 读取构建产物 | ||
| - **AND** 两个平台使用相同的构建配置 | ||
|
|
||
| #### Scenario: GitHub Actions 版本统一 | ||
| - **WHEN** 任何 GitHub Actions 工作流执行 | ||
| - **THEN** 所有工作流使用 `actions/checkout@v4` | ||
| - **AND** 所有工作流使用 `actions/setup-node@v4` | ||
| - **AND** Node.js 版本统一配置为 `20` | ||
| - **AND** 依赖缓存策略一致使用 `cache: "npm"` | ||
|
|
||
| #### Scenario: 构建产物结构 | ||
| - **WHEN** 执行生产构建 | ||
| - **THEN** 生成符合部署平台要求的目录结构 | ||
| - **AND** 构建产物可直接部署到 GitHub Pages 或 Azure Static Web Apps | ||
| - **AND** 包含所有必需的静态资源（HTML、CSS、JS、字体等） | ||
| - **AND** 包含 Azure Static Web Apps 配置文件 `staticwebapp.config.json` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,92 @@ | ||||||
| # 修复 Azure Static Web Apps 部署配置 - 任务列表 | ||||||
|
|
||||||
| ## 1. 分析参考配置 | ||||||
| - [ ] 1.1 阅读 `pcode-docs` 项目的 Azure Static Web Apps 工作流配置 | ||||||
| - [ ] 1.2 对比两个项目的构建配置差异（`vite.config.ts` 输出目录） | ||||||
| - [ ] 1.3 确认当前项目的构建输出目录为 `dist/` 而非 `build/` | ||||||
| - [ ] 1.4 验证 GitHub Pages 工作流使用的路径配置 | ||||||
|
|
||||||
| ## 2. 创建 Azure Static Web Apps 配置文件 | ||||||
| - [ ] 2.1 在 `public/` 目录下创建 `staticwebapp.config.json` 文件 | ||||||
| - [ ] 2.2 配置 `navigationFallback.rewrite` 为 `"index.html"` 以支持 React Router 客户端路由 | ||||||
| - [ ] 2.3 验证配置文件 JSON 格式正确性 | ||||||
| - [ ] 2.4 确认构建流程会将 `public/staticwebapp.config.json` 复制到 `dist/` 目录 | ||||||
|
|
||||||
| ## 3. 修复 Azure 工作流配置 | ||||||
| - [ ] 3.1 更新 `actions/checkout@v3` → `actions/checkout@v4` | ||||||
| - [ ] 3.2 添加显式 Node.js 设置步骤（使用 `actions/setup-node@v4`） | ||||||
| - [ ] 3.3 配置 Node.js 版本为 `20`（与 GitHub Pages 工作流一致） | ||||||
| - [ ] 3.4 添加 `npm ci` 依赖安装步骤 | ||||||
| - [ ] 3.5 添加 `npm run build` 构建步骤 | ||||||
| - [ ] 3.6 修改 `app_location` 从 `"/"` → `"dist"` | ||||||
| - [ ] 3.7 修改 `output_location` 从 `"build"` → 预留（使用 `skip_app_build: true` 后此参数被忽略） | ||||||
| - [ ] 3.8 添加 `skip_app_build: true` 配置（跳过 Azure 自动构建） | ||||||
| - [ ] 3.9 添加 `verbose: true` 启用详细日志用于调试 | ||||||
| - [ ] 3.10 添加环境变量 `NODE_VERSION: '20'`（可选，用于文档说明） | ||||||
|
|
||||||
| ## 4. 优化工作流结构 | ||||||
| - [ ] 4.1 为构建步骤添加清晰的注释说明 | ||||||
| - [ ] 4.2 保留 OIDC 认证步骤（维持现有安全机制） | ||||||
| - [ ] 4.3 确认 Close Pull Request Job 步骤保持不变 | ||||||
| - [ ] 4.4 验证 permissions 配置完整性（`id-token: write`, `contents: read`） | ||||||
|
|
||||||
| ## 5. 验证配置正确性 | ||||||
| - [ ] 5.1 确认构建输出目录 `dist/` 与 `vite.config.ts` 中的 `outDir` 配置一致 | ||||||
| - [ ] 5.2 确认 `public/staticwebapp.config.json` 被复制到 `dist/` 目录 | ||||||
| - [ ] 5.3 确认 GitHub Pages 工作流不受影响（仍使用 `dist/` 路径） | ||||||
| - [ ] 5.4 检查工作流 YAML 语法正确性 | ||||||
| - [ ] 5.5 验证所有必需的 secrets 配置（`AZURE_STATIC_WEB_APPS_API_TOKEN_AMBITIOUS_MOSS_03F17D600`） | ||||||
|
|
||||||
| ## 6. 测试和部署 | ||||||
| - [ ] 6.1 创建功能分支提交工作流配置修改和 staticwebapp.config.json | ||||||
| - [ ] 6.2 通过 Pull Request 触发 Azure Static Web Apps 预览部署 | ||||||
| - [ ] 6.3 验证预览环境构建和部署成功 | ||||||
| - [ ] 6.4 检查 Azure 部署日志确认无错误 | ||||||
| - [ ] 6.5 测试预览环境应用功能正常运行 | ||||||
| - [ ] 6.6 **测试 React Router 客户端路由**：直接访问非根路径（如 `/generator`），确认返回 `index.html` 而非 404 | ||||||
| - [ ] 6.7 合并到 main 分支触发生产环境部署 | ||||||
| - [ ] 6.8 验证生产环境部署成功 | ||||||
| - [ ] 6.9 验证生产环境客户端路由正常工作 | ||||||
|
|
||||||
| ## 依赖关系 | ||||||
| - 任务 1 必须首先完成，为后续修改提供依据 | ||||||
| - 任务 2 和 3 可以并行执行（配置文件创建和工作流配置修改） | ||||||
| - 任务 4 必须在任务 2、3 完成后执行 | ||||||
| - 任务 5 必须在任务 4 完成后执行 | ||||||
| - 任务 6 必须在任务 5 完成后执行 | ||||||
|
|
||||||
| ## 可交付成果 | ||||||
| - 新建的 `public/staticwebapp.config.json` 配置文件 | ||||||
| - 更新后的 `.github/workflows/azure-static-web-apps-ambitious-moss-03f17d600.yml` | ||||||
| - 成功部署到 Azure Static Web Apps 的应用 | ||||||
| - 验证通过的部署测试记录（包括客户端路由测试） | ||||||
|
|
||||||
| ## 回滚计划 | ||||||
| 如果修复后部署失败： | ||||||
| 1. 检查 Azure 部署日志中的具体错误信息 | ||||||
| 2. 验证 `dist/` 目录是否正确生成 | ||||||
| 3. 验证 `dist/staticwebapp.config.json` 是否存在 | ||||||
| 4. 确认 Node.js 版本和依赖安装是否成功 | ||||||
| 5. 如需回滚，删除 `public/staticwebapp.config.json` 并恢复原始工作流配置文件 | ||||||
|
|
||||||
| ## staticwebapp.config.json 配置说明 | ||||||
| 此文件是 Azure Static Web Apps 的必需配置，用于处理单页应用（SPA）的客户端路由： | ||||||
|
There was a problem hiding this comment. Wording polish: use “必要配置/必须的配置” instead of “必需配置”. This reads more naturally in Chinese technical docs. ✏️ Suggested edit-此文件是 Azure Static Web Apps 的必需配置，用于处理单页应用（SPA）的客户端路由：
+此文件是 Azure Static Web Apps 的必要配置，用于处理单页应用（SPA）的客户端路由：📝 Committable suggestion
Suggested change
🧰 Tools🪛 LanguageTool[uncategorized] ~73-~73: "必需"后面不应接动词，您的意思是""必须""吗？ (ZH2) 🤖 Prompt for AI Agents |
||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "navigationFallback": { | ||||||
| "rewrite": "index.html" | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| **作用**： | ||||||
| - 当用户访问任何路径（如 `/generator`、`/about`）时 | ||||||
| - 如果该路径不是实际文件（如 .js、.css、图片等） | ||||||
| - Azure Static Web Apps 将返回 `index.html` | ||||||
| - React Router 接管后渲染正确的组件 | ||||||
|
|
||||||
| **重要性**： | ||||||
| - 没有此配置，直接访问非根路径将返回 404 | ||||||
| - 刷新页面时客户端路由会失效 | ||||||
| - 与 GitHub Pages 的 404 重定向机制类似 | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| { | ||
| "navigationFallback": { | ||
| "rewrite": "index.html" | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fix the execution date mismatch.
This change is archived under 2026-02-05 and the PR was created on 2026-02-05, but the execution date says 2025-02-05. That should be 2026-02-05 to avoid timeline confusion.
📅 Suggested fix
📝 Committable suggestion
🤖 Prompt for AI Agents