Back to Details

deploy-site

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deploy Power Pages Code Site

部署Power Pages代码站点

Guide the user through deploying an existing Power Pages code site to a Power Pages environment using PAC CLI. Follow a systematic approach: verify tooling, authenticate, confirm the target environment, build and upload the site, and handle any blockers.
指导用户使用PAC CLI将现有的Power Pages代码站点部署到Power Pages环境。遵循系统化步骤：验证工具、认证身份、确认目标环境、构建并上传站点，以及处理任何阻碍问题。

Core Principles

核心原则

  • Verify before acting: Always confirm PAC CLI availability, authentication status, and the target environment before attempting any deployment.
  • Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
  • Never change environment settings without consent: If deployment requires modifying environment configuration (e.g., unblocking JavaScript attachments), always explain the change and get explicit user permission first.
Initial request: $ARGUMENTS
  • 行动前先验证：在尝试任何部署操作前，务必确认PAC CLI可用、认证状态有效以及目标环境正确。
  • 使用TaskCreate/TaskUpdate：跟踪所有阶段的进度——在开始任何工作前，预先创建包含所有阶段的待办事项列表。
  • 未经许可绝不修改环境设置：如果部署需要修改环境配置（例如解除JavaScript附件的阻止），务必先向用户说明更改内容并获得明确许可。
初始请求：$ARGUMENTS

Phase 1: Verify PAC CLI

阶段1：验证PAC CLI

Goal: Ensure PAC CLI is installed and available on the system PATH
Actions:
  1. Create todo list with all 6 phases (see Progress Tracking table)
  2. Run 
    pac help
    to check if the PAC CLI is installed and available on the system PATH.
    powershell
    pac help
  3. If the command succeeds: PAC CLI is installed. Proceed to Phase 2.
  4. If the command fails (command not found / not recognized):
    1. Inform the user that PAC CLI is required but not installed.
    2. Fetch installation instructions from 
      https://aka.ms/PowerPlatformCLI
      using the following approach:
      • Tell the user: "PAC CLI is not installed. You can install it by running:"
        powershell
        dotnet tool install --global Microsoft.PowerApps.CLI.Tool
      • If 
        dotnet
        is also not available, direct the user to https://aka.ms/PowerPlatformCLI for full installation instructions including .NET SDK setup.
    3. After installation, verify by running 
      pac help
      again.
    4. If it still fails, stop and ask the user to resolve the installation manually.
Output: PAC CLI installed and verified
目标：确保PAC CLI已安装且可在系统PATH中访问
操作：
  1. 使用
    TaskCreate
    创建包含全部6个阶段的任务列表（见下方【进度跟踪】表格）
  2. 运行
    pac help
    命令，检查PAC CLI是否已安装且可在系统PATH中访问。
    powershell
    pac help
  3. 若命令执行成功：PAC CLI已安装，进入阶段2。
  4. 若命令执行失败（命令未找到/无法识别）：
    1. 告知用户需要PAC CLI但尚未安装。
    2. 通过以下方式从
      https://aka.ms/PowerPlatformCLI
      获取安装说明：
      • 告知用户：“PAC CLI未安装。您可以运行以下命令进行安装：”
        powershell
        dotnet tool install --global Microsoft.PowerApps.CLI.Tool
      • 如果
        dotnet
        也不可用，引导用户访问https://aka.ms/PowerPlatformCLI查看完整安装说明，包括.NET SDK的安装步骤。
    3. 安装完成后，再次运行
      pac help
      进行验证。
    4. 若仍失败，停止操作并请用户手动解决安装问题。
输出：PAC CLI已安装并验证通过

Phase 2: Verify Authentication

阶段2：验证身份认证

Goal: Ensure the user is authenticated with PAC CLI and has a valid session
Actions:
  1. Run 
    pac auth who
    to check the current authentication status.
    powershell
    pac auth who
  2. If authenticated: Extract the following values from the output:
    • Environment name and URL
    • Environment ID — the GUID after 
      Environment ID:
    • Cloud — the value after 
      Cloud:
      (e.g., 
      Public
      , 
      UsGov
      , 
      UsGovHigh
      , 
      UsGovDod
      , 
      China
      )
    Proceed to Phase 3.
  3. If not authenticated:
    1. Inform the user they are not authenticated with PAC CLI.
    2. Use 
      AskUserQuestion
      to ask for the environment URL:
      QuestionHeaderOptions
      You are not authenticated with PAC CLI. Please provide your Power Pages environment URL (e.g., 
      https://org12345.crm.dynamics.com
      ) so I can authenticate you.      		Auth(free text input via "Other")
      Provide two placeholder options to guide the user:
      • "I'll paste the URL" (description: "Select 'Other' below and paste your environment URL")
      • "I don't know my URL" (description: "You can find it in the Power Platform admin center under Environments > your environment > Environment URL")
    3. Once the user provides the URL, run the authentication command:
      powershell
      pac auth create --environment "<USER_PROVIDED_URL>"
      This will open a browser window for the user to sign in.
    4. After the command completes, verify by running 
      pac auth who
      again.
    5. If authentication succeeds, proceed to Phase 3.
    6. If authentication fails, present the error to the user and help them troubleshoot.
Output: Authenticated PAC CLI session with environment name and URL extracted
目标：确保用户已通过PAC CLI认证并拥有有效会话
操作：
  1. 运行
    pac auth who
    命令检查当前认证状态。
    powershell
    pac auth who
  2. 若已认证：从输出中提取以下信息：
    • 环境名称和URL
    • 环境ID —— 
      Environment ID:
      后的GUID
    • 云环境 —— 
      Cloud:
      后的值（例如：
      Public
      、
      UsGov
      、
      UsGovHigh
      、
      UsGovDod
      、
      China
      ）
    进入阶段3。
  3. 若未认证：
    1. 告知用户尚未通过PAC CLI认证。
    2. 使用
      AskUserQuestion
      询问用户环境URL：
      问题标题选项
      您尚未通过PAC CLI认证。请提供您的Power Pages环境URL（例如：
      https://org12345.crm.dynamics.com
      ）以便为您完成认证。      		身份认证（通过“其他”选项进行自由文本输入）
      提供两个占位选项引导用户：
      • “我将粘贴URL”（说明：“选择下方的‘其他’并粘贴您的环境URL”）
      • “我不知道我的URL”（说明：“您可以在Power Platform管理中心的‘环境>您的环境>环境URL’中找到它”）
    3. 用户提供URL后，运行认证命令：
      powershell
      pac auth create --environment "<USER_PROVIDED_URL>"
      这将打开浏览器窗口供用户登录。
    4. 命令完成后，再次运行
      pac auth who
      进行验证。
    5. 若认证成功，进入阶段3。
    6. 若认证失败，向用户展示错误信息并协助排查问题。
输出：已获取带环境名称和URL的PAC CLI认证会话

Phase 3: Confirm Environment

阶段3：确认目标环境

Goal: Ensure the user is deploying to the correct target environment
Actions:
  1. Present the current environment information to the user and ask them to confirm.
    Use 
    AskUserQuestion
    with the following structure:
    QuestionHeaderOptions
    You are currently connected to environment: <ENV_NAME> (<ENV_URL>). Do you want to deploy to this environment?EnvironmentYes, use this environment, No, let me choose a different one
  2. If "Yes, use this environment": Proceed to Phase 4.
  3. If "No, let me choose a different one":
    1. Run 
      pac org list
      to retrieve all available environments:
      powershell
      pac org list
    2. Parse the output to extract environment names and URLs.
    3. Use 
      AskUserQuestion
      to present the available environments as options (pick up to 4 most relevant, or let user specify).
    4. Once the user selects an environment, switch to it:
      powershell
      pac org select --environment "<SELECTED_ENV_ID_OR_URL>"
    5. Verify the switch by running 
      pac auth who
      again.
Output: Confirmed target environment for deployment
目标：确保用户部署到正确的目标环境
操作：
  1. 向用户展示当前环境信息并请求确认。
    使用
    AskUserQuestion
    ，结构如下：
    问题标题选项
    您当前已连接到环境：<ENV_NAME>（<ENV_URL>）。是否要部署到此环境？环境确认是，使用此环境；否，让我选择其他环境
  2. 若选择“是，使用此环境”：进入阶段4。
  3. 若选择“否，让我选择其他环境”：
    1. 运行
      pac org list
      命令获取所有可用环境：
      powershell
      pac org list
    2. 解析输出内容，提取环境名称和URL。
    3. 使用
      AskUserQuestion
      将可用环境作为选项展示给用户（最多显示4个最相关的，或让用户自行指定）。
    4. 用户选择环境后，切换到该环境：
      powershell
      pac org select --environment "<SELECTED_ENV_ID_OR_URL>"
    5. 再次运行
      pac auth who
      验证切换是否成功。
输出：已确认部署的目标环境

Phase 4: Deploy the Code Site

阶段4：部署代码站点

Goal: Locate the project, build it, and upload to Power Pages
Actions:
目标：定位项目、构建站点并上传到Power Pages
操作：

4.1 Locate the Project Root

4.1 定位项目根目录

Determine the project root directory. The project root is the directory containing 
powerpages.config.json
. Use 
Glob
to search for it:
text
**/powerpages.config.json
If found in the current working directory or a subdirectory, use that directory as 
PROJECT_ROOT
. If multiple are found, ask the user which one to deploy using 
AskUserQuestion
.
If not found, ask the user to provide the path to the project root.
确定项目根目录。项目根目录是包含
powerpages.config.json
文件的目录。使用
Glob
命令搜索该文件：
text
**/powerpages.config.json
如果在当前工作目录或子目录中找到该文件，将该目录设为
PROJECT_ROOT
。如果找到多个，使用
AskUserQuestion
询问用户要部署哪个项目。
如果未找到，请用户提供项目根目录的路径。

4.2 Offer Permissions Audit (Redeployments Only)

4.2 提供权限审计选项（仅针对重新部署）

If 
.powerpages-site
already exists (i.e., this is not the first deployment), table permissions and site settings may have drifted from the code since the last deployment. Offer to audit before deploying.
Use 
AskUserQuestion
:
QuestionHeaderOptions
This site has been deployed before. Would you like to run a permissions audit to verify table permissions match your current code before deploying?AuditYes, audit permissions (Recommended), Skip — permissions are up to date
If "Yes": Invoke 
/audit-permissions
to run the audit. After the audit completes, resume with Step 4.3. If "Skip": Proceed to Step 4.3.
If 
.powerpages-site
does not exist (first deployment), skip this step — there are no existing permissions to audit.
如果
.powerpages-site
目录已存在（即不是首次部署），表权限和站点设置可能与上次部署后的代码出现偏差。在部署前提供审计选项。
使用
AskUserQuestion
：
问题标题选项
此站点已部署过。是否要在部署前运行权限审计，验证表权限是否与当前代码一致？权限审计是，进行权限审计（推荐）；跳过——权限已更新至最新
若选择“是”：调用
/audit-permissions
运行审计。审计完成后，继续执行步骤4.3。 若选择“跳过”：直接进入步骤4.3。
如果
.powerpages-site
目录不存在（首次部署），跳过此步骤——没有现有权限需要审计。

4.3 Build the Site

4.3 构建站点

Before uploading, ensure the site is built:
powershell
cd "<PROJECT_ROOT>"
npm run build
If the build fails, stop and help the user fix the build errors before retrying.
上传前，确保站点已构建完成：
powershell
cd "<PROJECT_ROOT>"
npm run build
如果构建失败，停止操作并协助用户修复构建错误后再重试。

4.4 Upload to Power Pages

4.4 上传到Power Pages

Run the upload command:
powershell
pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
If the upload succeeds: Proceed to Phase 5 to verify the deployment.
If the upload fails: Check the error message:
  • If the failure is related to blocked JavaScript (
    .js
    ) attachments → proceed to Phase 6
  • If the failure mentions 
    .html
    type attachments are currently blocked     → this is a misleading error. See Troubleshooting: HTML Blocked Attachment Error below
  • For other errors → present the error to the user and help them troubleshoot
Output: Site built and uploaded to Power Pages
运行上传命令：
powershell
pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
若上传成功：进入阶段5验证部署结果。
若上传失败：检查错误信息：
  • 如果失败与JavaScript（.js）附件被阻止相关 → 进入阶段6
  • 如果失败提示**“当前环境阻止.html类型的附件”** → 这是一个误导性错误。请查看下方【故障排查：HTML附件被阻止错误】
  • 其他错误 → 向用户展示错误信息并协助排查
输出：站点已构建并上传到Power Pages

Phase 5: Verify Deployment

阶段5：验证部署结果

Goal: Confirm the deployment was successful and handle post-deployment steps
Actions:
目标：确认部署成功并处理部署后步骤
操作：

5.1 Verify 
.powerpages-site
Folder

5.1 验证.powerpages-site目录

Confirm 
.powerpages-site
exists and list its contents (
web-roles/
, 
site-settings/
, 
table-permissions/
).
确认
.powerpages-site
目录存在并列出其内容（
web-roles/
、
site-settings/
、
table-permissions/
）。

5.2 Record Skill Usage

5.2 记录技能使用情况

Reference: 
${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md
Follow the skill tracking instructions in the reference to record this skill's usage. Use 
--skillName "DeploySite"
.
参考：
${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md
按照参考文档中的技能跟踪说明记录本技能的使用情况，使用
--skillName "DeploySite"
参数。

5.3 Confirm Upload Output

5.3 确认上传输出

Review the output from the 
pac pages upload-code-site
command in Phase 4 (or Phase 6 retry). Verify it reported a successful upload with no errors.
查看阶段4（或阶段6重试）中
pac pages upload-code-site
命令的输出，验证是否显示上传成功且无错误。

5.4 Commit Changes

5.4 提交变更

Stage and commit deployment artifacts:
powershell
git add -A
git commit -m "Deploy site to Power Pages"
暂存并提交部署工件：
powershell
git add -A
git commit -m "Deploy site to Power Pages"

5.5 Check Activation Status

5.5 检查激活状态

Run the activation status check:
powershell
node "${CLAUDE_PLUGIN_ROOT}/scripts/check-activation-status.js" --projectRoot "<PROJECT_ROOT>"
Evaluate the JSON result:
  • If 
    activated
    is 
    true
    : Inform the user their site is already activated (show 
    websiteUrl
    if present). Proceed to step 5.6, then skip to Suggest Next Steps. Do NOT ask about activation.
  • If 
    activated
    is 
    false
    : Proceed to step 5.5.1.
  • If 
    error
    is present    : Fall back to step 5.5.1. Do not block the deployment flow.
运行激活状态检查命令：
powershell
node "${CLAUDE_PLUGIN_ROOT}/scripts/check-activation-status.js" --projectRoot "<PROJECT_ROOT>"
解析JSON结果：
  • 若
    activated
    为
    true
    ：告知用户站点已激活（若存在
    websiteUrl
    则一并展示）。进入步骤5.6，然后跳转到【后续步骤建议】。无需询问激活相关问题。
  • 若
    activated
    为
    false
    ：进入步骤5.5.1。
  • 若存在
    error
    ：回退到步骤5.5.1，不要中断部署流程。

5.5.1 Ask About Activation (only if site is NOT already activated)

5.5.1 询问是否激活站点（仅当站点未激活时）

Ask the user if they want to activate the site using 
AskUserQuestion
:
QuestionHeaderOptions
Site deployed successfully! Would you like to activate (provision) the site now so it gets a live URL?ActivateActivate now (Recommended) — Provision the site with a subdomain and make it live, Skip for now — I'll activate later
If "Activate now": Invoke the 
/activate-site
skill. After activation completes, proceed to step 5.6 to clear the site cache. If "Skip for now": Suggest next steps (see Suggest Next Steps).
使用
AskUserQuestion
询问用户是否要激活站点：
问题标题选项
站点部署成功！是否要立即激活（配置）站点，使其获得可用的在线URL？站点激活立即激活（推荐）——为站点配置子域名并上线；稍后激活——我将手动激活
若选择“立即激活”：调用
/activate-site
技能。激活完成后，进入步骤5.6清除站点缓存。 若选择“稍后激活”：查看【后续步骤建议】。

5.6 Clear Site Cache (Only If Activated)

5.6 清除站点缓存（仅当站点已激活时）

After confirming the site is activated (either it was already activated in step 5.5, or the user just activated it in step 5.5.1), offer to clear the runtime cache so the deployed changes are immediately visible.
Prerequisites: The site must be activated and the project root must be known (from Phase 4.1).
Use 
AskUserQuestion
to confirm before proceeding:
QuestionHeaderOptions
Would you like to restart the site so your latest changes are immediately visible? This may cause a brief downtime (a few seconds).RestartYes, restart site (Recommended), Skip — I'll restart later
If "Skip": Skip to Suggest Next Steps.
If "Yes": Run the cache-clearing script, passing the project root:
powershell
node "${CLAUDE_PLUGIN_ROOT}/scripts/clear-site-cache.js" --projectRoot "<PROJECT_ROOT>"
The script reads 
siteName
from 
powerpages.config.json
, looks up the website via the Power Platform admin API, and restarts it to flush the runtime cache.
Evaluate the result:
  • If 
    success
    is 
    true
    : Inform the user: "Site cache cleared — your latest changes should now be visible at <websiteUrl>."
  • If 
    success
    is 
    false
    : Warn the user that cache clearing failed and show the error, but do not block the deployment flow. The deployment itself succeeded; cache will eventually refresh on its own. Suggest the user can manually clear cache from the Power Pages admin center if needed.
Output: Deployment verified, changes committed, activation offered, cache cleared
确认站点已激活后（无论是步骤5.5中发现已激活，还是用户刚在步骤5.5.1中完成激活），提供清除运行时缓存的选项，使部署的变更立即生效。
前提条件：站点已激活且已知项目根目录（来自阶段4.1）。
使用
AskUserQuestion
确认后再执行：
问题标题选项
是否要重启站点，使您的最新变更立即生效？这可能会导致短暂的停机（几秒时间）。站点重启是，重启站点（推荐）；跳过——我稍后手动重启
若选择“跳过”：跳转到【后续步骤建议】。
若选择“是”：运行清除缓存脚本，传入项目根目录参数：
powershell
node "${CLAUDE_PLUGIN_ROOT}/scripts/clear-site-cache.js" --projectRoot "<PROJECT_ROOT>"
该脚本从
powerpages.config.json
中读取
siteName
，通过Power Platform管理API查找对应网站并重启，以清除运行时缓存。
解析执行结果：
  • 若
    success
    为
    true
    ：告知用户：“站点缓存已清除——您的最新变更现在应该已在**<websiteUrl>**生效。”
  • 若
    success
    为
    false
    ：警告用户缓存清除失败并显示错误信息，但不要中断部署流程。部署本身已成功，缓存最终会自动刷新。建议用户如有需要可从Power Pages管理中心手动清除缓存。
输出：部署已验证，变更已提交，激活选项已提供，缓存已清除

Phase 6: Handle Blocked JavaScript

阶段6：处理JavaScript被阻止问题

Goal: Resolve blocked JavaScript attachment errors and retry deployment
Actions:
目标：解决JavaScript附件被阻止的错误并重试部署
操作：

6.1 Explain the Issue

6.1 说明问题

Tell the user:
"The upload failed because JavaScript (.js) file attachments are blocked in your Power Pages environment. This is a security setting that prevents uploading .js files. To deploy a code site, this restriction needs to be relaxed for .js files."
告知用户：
“上传失败，因为您的Power Pages环境中阻止了JavaScript（.js）文件附件。这是一项安全设置，用于阻止上传.js文件。要部署代码站点，需要放宽对.js文件的限制。”

6.2 Ask for Permission

6.2 请求许可

Use 
AskUserQuestion
:
QuestionHeaderOptions
Would you like to remove the JavaScript (.js) block from the environment's blocked attachments list? This is required to deploy code sites.Unblock JSYes, remove the .js block (Recommended), No, do not change environment settings
If "No": Stop and inform the user that the deployment cannot proceed without unblocking 
.js
attachments.
If "Yes": Proceed to 6.3.
使用
AskUserQuestion
：
问题标题选项
是否要从环境的阻止附件列表中移除JavaScript（.js）的阻止？这是部署代码站点的必要操作。解除JS阻止是，移除.js阻止（推荐）；否，不要修改环境设置
若选择“否”：停止操作并告知用户，不解除.js附件阻止则无法继续部署。
若选择“是”：进入6.3。

6.3 Update Blocked Attachments

6.3 更新阻止附件设置

  1. Run 
    pac env list-settings
    to retrieve the current environment settings:
    powershell
    pac env list-settings
  2. Find the 
    blockedattachments
    property in the output. It will contain a semicolon-separated list of file extensions (e.g., 
    ade;adp;app;asa;ashx;asmx;asp;bas;bat;cdx;cer;chm;class;cmd;com;config;cnt;cpl;crt;csh;der;dll;exe;fxp;hlp;hta;htr;htw;ida;idc;idq;inf;ins;isp;its;js;jse;ksh;lnk;mad;maf;mag;mam;maq;mar;mas;mat;mau;mav;maw;mda;mdb;mde;mdt;mdw;mdz;msc;msh;msh1;msh1xml;msh2;msh2xml;mshxml;msi;msp;mst;ops;pcd;pif;prf;prg;printer;pst;reg;rem;scf;scr;sct;shb;shs;shtm;shtml;soap;stm;tmp;url;vb;vbe;vbs;vsmacros;vss;vst;vsw;ws;wsc;wsf;wsh
    ).
  3. Remove 
    js
    from the list. Parse the semicolon-separated values, filter out 
    js
    , and rejoin with semicolons.
  4. Update the setting:
    powershell
    pac env update-settings --name blockedattachments --value "<UPDATED_LIST_WITHOUT_JS>"
  5. Confirm the update was successful.
  1. 运行
    pac env list-settings
    命令获取当前环境设置：
    powershell
    pac env list-settings
  2. 在输出中找到
    blockedattachments
    属性，它包含一个用分号分隔的文件扩展名列表（例如：
    ade;adp;app;asa;ashx;asmx;asp;bas;bat;cdx;cer;chm;class;cmd;com;config;cnt;cpl;crt;csh;der;dll;exe;fxp;hlp;hta;htr;htw;ida;idc;idq;inf;ins;isp;its;js;jse;ksh;lnk;mad;maf;mag;mam;maq;mar;mas;mat;mau;mav;maw;mda;mdb;mde;mdt;mdw;mdz;msc;msh;msh1;msh1xml;msh2;msh2xml;mshxml;msi;msp;mst;ops;pcd;pif;prf;prg;printer;pst;reg;rem;scf;scr;sct;shb;shs;shtm;shtml;soap;stm;tmp;url;vb;vbe;vbs;vsmacros;vss;vst;vsw;ws;wsc;wsf;wsh
    ）。
  3. 从列表中移除
    js
    。解析分号分隔的值，过滤掉
    js
    ，再用分号重新连接。
  4. 更新设置：
    powershell
    pac env update-settings --name blockedattachments --value "<UPDATED_LIST_WITHOUT_JS>"
  5. 确认更新成功。

6.4 Retry Upload

6.4 重试上传

Run the upload command again:
powershell
pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
If it succeeds: Proceed to Phase 5 to verify the deployment.
If it fails again with a different error, present the error to the user and help troubleshoot.
Output: JavaScript unblocked and site deployed successfully
再次运行上传命令：
powershell
pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
如果成功：进入阶段5验证部署结果。
如果再次失败且错误不同，向用户展示错误信息并协助排查。
输出：JavaScript已解除阻止，站点部署成功

Troubleshooting: HTML Blocked Attachment Error

故障排查：HTML附件被阻止错误

If the upload fails with an error like:
Error: Unable to upload webfile name 'index.html' with record Id <GUID> as '.html' type attachments are currently blocked on this environment.
This error is misleading. The 
.html
extension is not actually blocked — the real cause is a stale environment manifest file in the 
.powerpages-site
folder. This manifest maps local files to Dataverse record IDs from a previous upload. When the mapping becomes outdated (e.g., after environment changes or record deletions), the upload fails with this confusing error.
如果上传失败并出现如下错误：
Error: Unable to upload webfile name 'index.html' with record Id <GUID> as '.html' type attachments are currently blocked on this environment.
此信息具有误导性。
.html
扩展名并未被实际阻止——真正原因是
.powerpages-site
目录中的环境清单文件已过期。该清单文件将本地文件映射到上次上传时的Dataverse记录ID。当映射过期时（例如环境变更或记录删除后），上传会失败并显示这个易混淆的错误。

Fix

修复方法

  1. Locate the environment-specific manifest file in the 
    .powerpages-site
    folder. It follows the naming pattern 
    <environment-host>-manifest.yml
    (e.g., 
    demo1.crm.dynamics.com-manifest.yml
    ). List the folder contents to find it:
    powershell
    Get-ChildItem -Path "<PROJECT_ROOT>/.powerpages-site" -Filter "*-manifest.yml"
  2. Delete the manifest file:
    powershell
    Remove-Item -Path "<PROJECT_ROOT>/.powerpages-site/<environment-host>-manifest.yml"
  3. Retry the upload:
    powershell
    pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
If the retry succeeds, proceed to Phase 5. If it fails with a different error, present the error to the user and help them troubleshoot.
Important: Do NOT attempt to unblock 
.html
in the environment's blocked attachments list — the error is not caused by the attachment block setting.
  1. 在
    .powerpages-site
    目录中找到环境特定的清单文件，其命名格式为
    <environment-host>-manifest.yml
    （例如：
    demo1.crm.dynamics.com-manifest.yml
    ）。列出目录内容以找到该文件：
    powershell
    Get-ChildItem -Path "<PROJECT_ROOT>/.powerpages-site" -Filter "*-manifest.yml"
  2. 删除该清单文件：
    powershell
    Remove-Item -Path "<PROJECT_ROOT>/.powerpages-site/<environment-host>-manifest.yml"
  3. 重试上传：
    powershell
    pac pages upload-code-site --rootPath "<PROJECT_ROOT>"
如果重试成功，进入阶段5。如果再次失败且错误不同，向用户展示错误信息并协助排查。
重要提示：不要尝试在环境的阻止附件列表中解除
.html
的阻止——错误并非由附件阻止设置导致。

Suggest Next Steps

后续步骤建议

If the user skips activation (or after activation completes), suggest:
  • /activate-site
    — Provision the site with a subdomain and make it live (if not already activated)
  • /test-site
    — Test the deployed site in the browser (verify pages load, check API calls)
  • /audit-permissions
    — Audit table permissions against current code (recommended after redeployments)
  • /setup-datamodel
    — Create Dataverse tables for dynamic content
  • /add-seo
    — Add meta tags, robots.txt, sitemap.xml, favicon
如果用户跳过激活（或激活完成后），建议：
  • /activate-site
    —— 为站点配置子域名并上线（若尚未激活）
  • /test-site
    —— 在浏览器中测试已部署的站点（验证页面加载、API调用）
  • /audit-permissions
    —— 对照当前代码审计表权限（重新部署后推荐执行）
  • /setup-datamodel
    —— 为动态内容创建Dataverse表
  • /add-seo
    —— 添加元标签、robots.txt、sitemap.xml、网站图标

Important Notes

重要注意事项

NEVER Use 
pac pages upload

切勿使用
pac pages upload

Always use 
pac pages upload-code-site
— never use 
pac pages upload
. The 
pac pages upload
command is designed for portal-studio-style sites and will corrupt code site metadata if used on a code site project. This applies to every upload step in this skill (Phase 4.4, Phase 6.4, and troubleshooting retries).
始终使用
pac pages upload-code-site
——绝不使用
pac pages upload
。
pac pages upload
命令专为Portal Studio风格的站点设计，若用于代码站点项目会损坏元数据。本技能的所有上传步骤（阶段4.4、阶段6.4以及故障排查中的重试）均适用此规则。

Throughout All Phases

所有阶段通用规则

  • Use TaskCreate/TaskUpdate to track progress at every phase
  • Ask for user confirmation at key decision points (see list below)
  • Present errors clearly — when a command fails, show the user the relevant error output and explain what went wrong before suggesting fixes
  • 使用TaskCreate/TaskUpdate跟踪每个阶段的进度
  • 在关键决策点请求用户确认（见下方列表）
  • 清晰展示错误信息——命令失败时，向用户展示相关错误输出并解释问题原因，然后再提出修复建议

Key Decision Points (Wait for User)

关键决策点（需等待用户操作）

  1. After Phase 2: If not authenticated, get environment URL from user
  2. At Phase 3: Confirm or switch the target environment
  3. At Phase 4.1: If multiple 
    powerpages.config.json
    found, ask which project to deploy
  4. At Phase 4.2: Audit permissions now or skip (redeployments only)
  5. At Phase 5.5: Activate site now or later
  6. At Phase 6: Get permission before modifying blocked attachments setting
  1. 阶段2之后：若未认证，向用户获取环境URL
  2. 阶段3：确认或切换目标环境
  3. 阶段4.1：若找到多个
    powerpages.config.json
    ，询问用户要部署哪个项目
  4. 阶段4.2：是否立即审计权限或跳过（仅针对重新部署）
  5. 阶段5.5：立即激活站点还是稍后激活
  6. 阶段6：修改阻止附件设置前获取用户许可

Progress Tracking

进度跟踪

Before starting Phase 1, create a task list with all phases using 
TaskCreate
:
Task subjectactiveFormDescription
Verify PAC CLI installationVerifying PAC CLICheck if PAC CLI is installed, install if missing
Verify authenticationVerifying authenticationCheck current auth status, authenticate if needed
Confirm target environmentConfirming environmentShow current environment, let user confirm or switch
Deploy the code siteDeploying siteLocate project root, build, and upload via pac pages upload-code-site
Verify deploymentVerifying deploymentConfirm .powerpages-site folder exists, review upload output, commit changes, offer activation
Handle blocked JavaScriptResolving JS blockIf upload fails due to blocked JS, offer to unblock and retry
Mark each task 
in_progress
when starting it and 
completed
when done via 
TaskUpdate
. Phase 6 may be marked 
completed
immediately if no JavaScript blocking issue is encountered. This gives the user visibility into progress and keeps the workflow deterministic.
Begin with Phase 1: Verify PAC CLI
在开始阶段1前，使用
TaskCreate
创建包含所有阶段的任务列表：
任务主题activeForm描述
验证PAC CLI安装验证PAC CLI检查PAC CLI是否已安装，若缺失则进行安装
验证身份认证验证身份认证检查当前认证状态，若需要则完成认证
确认目标环境确认环境展示当前环境，让用户确认或切换
部署代码站点部署站点定位项目根目录、构建站点并通过pac pages upload-code-site上传
验证部署结果验证部署确认.powerpages-site目录存在、查看上传输出、提交变更、提供激活选项
处理JavaScript被阻止问题解决JS阻止问题若上传因JS被阻止失败，提供解除阻止并重试的选项
开始每个阶段时，将对应任务标记为
in_progress
；完成后标记为
completed
（通过
TaskUpdate
）。如果未遇到JavaScript阻止问题，阶段6可直接标记为
completed
。这能让用户清晰看到进度并确保工作流程可预测。
从阶段1开始：验证PAC CLI