用途：本资料面向使用 Azure Container Apps 部署容器化应用的开发者，作为官方 azure-prepare 插件技能的补充，集中整理区域、认证、构建与前端部署方面的易错点。
主要能力与要点：
- ACR 认证：采用确定性的两阶段模式，用独立部署模块先创建带公共占位镜像和系统分配身份的 Container App，再授予 AcrPull，随后在依赖该角色分配的模块中更新 ACR 登录服务器与 identity: 'system'。单模块同时声明系统身份与 registry 可能触发 ACR 令牌交换 401。不同 azd 版本是否自动执行 registry set 不一致，首次私有镜像部署前需验证。
- 区域限制：AVM managed-environment 模块可能将 zoneRedundant 默认设为 true，westus 等区域不支持，需显式设为 false，否则 azd up 报错。
- azure.yaml：Docker 服务即使指定 docker.path 也必须写 language 或 image；docker.path 与 context 相对于服务项目文件夹，路径混用会导致 lstat 失败；由 azd 管理镜像的服务需声明 language 与 remoteBuild；公共镜像（如 Grafana、n8n）应只在 Bicep 中设置镜像，不要写成 azd 服务，否则打包时需本地 Docker，Windows 可能报 manifest 不匹配。
- 跨平台钩子：要求 azd 1.28.0+ 与 Node.js LTS+，使用 JS/TS 钩子，不用仅 Bash 或 PowerShell 的脚本；钩子须通过参数数组调用 az/azd，Windows 使用静态非插值 powershell.exe 启动器并传 JSON 环境载荷；镜像在 ACR 中构建，宿主无需 Docker。
- SPA 前端：VITE_API_URL 在构建期需注入，但 API URL 在预配后才已知；症状是前端报 Unexpected token '<' 并调用 /api 得到 index.html。方案是 postprovision/postdeploy 钩子读取 azd 环境值、按标签查找 web 应用、用 az acr build --platform linux/amd64 和 --build-arg 构建、更新应用并等待修订健康（minReplicas 为 0 时接受 Running 与 ScaledToZero）。
- 前端 Dockerfile 需在 npm run build 前用 ARG+ENV 传入 VITE_API_URL；nginx.conf 仅做 SPA 回退，不加 /api 代理；API 客户端以 import.meta.env.VITE_API_URL 回退 /api；.dockerignore 排除 node_modules、构建产物、数据库、.env 和 .git，但保留 tsconfig.json 与 package*.json。
- ARM64 宿主需 ACR linux/amd64 云构建，避免 exec format error。
- Bicep：uniqueString() 固定 13 字符，模块参数需同时声明 @minLength(13) 与 @maxLength(13)；输出用 SCREAMING_SNAKE_CASE 供 azd 读取。
- 其他：registry set 在身份刚创建后可能报 InternalServerError，应重试一次并用 registry list 确认；Windows 下 az acr build 建议加 --no-logs 避免 UnicodeEncodeError。
适用场景：Azure Container Apps 多服务部署、React/Vite SPA 与 API 分离部署、跨平台 azd 钩子、ACR 云构建与 Bicep 基础设施编排。
限制：资料未提供收费、价格、平台支持范围或效果保证；版本要求与区域限制以文中陈述为准，其他环境需自行验证。