将自定义脚本添加到 Windows 安装程序Add a Custom Script to Windows Setup

Windows 安装程序脚本setupcomplete.cmdErrorHandler 是在 Windows 安装程序过程中或之后运行的自定义脚本。Windows Setup scripts: Setupcomplete.cmd and ErrorHandler.cmd are custom scripts that run during or after the Windows Setup process. 它们可用于通过使用 cscript/wscript.echo 脚本来安装应用程序或运行其他任务。They can be used to install applications or run other tasks by using cscript/wscript scripts.

  • % WINDIR% \安装 \ 脚本 \ Setupcomplete.cmd:此脚本在用户看到桌面后立即运行。%WINDIR%\Setup\Scripts\SetupComplete.cmd: This script runs immediately after the user sees the desktop. 使用 OEM 产品密钥时,将禁用此设置。This setting is disabled when using OEM product keys. 它以本地系统权限运行。It runs with local system permission.
  • % WINDIR% \安装 \ 脚本 \ ErrorHandler:当安装程序遇到错误时,此脚本会自动运行。%WINDIR%\Setup\Scripts\ErrorHandler.cmd: This script runs automatically when Setup encounters a fatal error. 它以本地系统权限运行。It runs with local system permission.

Windows 无人参与脚本:创建一个 Unattend.xml 文件,其中包含其中一项设置,以便在 Windows 安装程序过程中运行。Windows Unattend scripts: Create an Unattend.xml file with one of these settings to run during the Windows Setup process. 这可与 OEM 产品密钥一起使用。This can be used with OEM product keys.

若要运行可同时启动的服务或命令,请使用 RunAsynchronousCommands。To run services or commands that can start at the same time, use RunAsynchronousCommands. 若要运行在其他命令可以启动之前需要完成的命令,请使用 RunSynchronousCommands。To run commands that need to finish before other commands can start, use RunSynchronousCommands.

注意 从 Windows 10 开始, Microsoft \ LogonCommands \ AsynchronousCommand 现在可以像 LogonCommands AsynchronousCommand 一样工作 \ :所有使用这些无人参与设置的命令现在都是同时启动的,不再等待上一个命令完成。Note As of Windows 10, Microsoft-Window-Shell-Setup\LogonCommands\AsynchronousCommand now works like LogonCommands\AsynchronousCommand: all commands using these unattend settings are now started at the same time, and no longer wait for the previous command to finish.

其中一些设置在用户上下文中运行,而其他设置则在系统上下文中运行,具体取决于配置阶段。Some of these settings run in the user context, others run in the system context depending on the configuration pass.

  • 添加 \ RunAsynchronousCommandRunSynchronousCommand ,以在 Windows 安装程序启动时运行脚本。Add Microsoft-Windows-Setup\RunAsynchronousCommand or RunSynchronousCommand to run a script as Windows Setup starts. 这有助于设置硬盘分区。This can be helpful for setting hard disk partitions.

  • \ RunAsynchronousCommandRunSynchronousCommand 添加到 auditUser 配置阶段,以运行在电脑进入审核模式时运行的脚本。Add Microsoft-Windows-Deployment\RunAsynchronousCommand or RunSynchronousCommand to the auditUser configuration pass to run a script that runs when the PC enters audit mode. 这对于自动应用安装或测试等任务非常有用。This can be helpful for tasks like automated app installation or testing.

  • 添加 \ LogonCommands \ AsynchronousCommandFirstLogonCommands \ SynchronousCommand ,使其在) 全新体验 (OOBE 后运行,但在用户看到桌面之前。Add Microsoft-Windows-Shell-Setup\LogonCommands\AsynchronousCommand or FirstLogonCommands\SynchronousCommand to run after the Out of Box Experience (OOBE) but before the user sees the desktop. 在用户已选择语言特定的应用或内容之后,这可能特别有用。This can be especially useful to set up language-specific apps or content after the user has already selected their language.

    请尽量少使用这些脚本,因为长脚本会阻止用户快速到达 "开始" 屏幕。Use these scripts sparingly because long scripts can prevent the user from reaching the Start screen quickly. 对于 Windows 零售版,其他限制适用于这些脚本。For retail versions of Windows, additional restrictions apply to these scripts. 有关信息,请参阅 OEM 合作伙伴中心上的许可和策略指南。For info, see the Licensing and Policy guidance on the OEM Partner Center.

    注意 使用 FirstLogonCommands 添加脚本时,它将在下一次启动时触发,即使使用 Ctrl + Shift + F3 进入审核模式也是如此。Note When you add a script using FirstLogonCommands, it will be triggered on the next boot, even if you boot into audit mode using Ctrl+Shift+F3. 若要在不触发这些脚本的情况下启动到审核模式,请添加设置: Microsoft-Windows 部署重新 \ 封装 \ 模式= audit。To boot to audit mode without triggering these scripts, add the setting: Microsoft-Windows-Deployment\Reseal\Mode = Audit.

安装完成后运行脚本 (Setupcomplete.cmd) Run a script after setup is complete (SetupComplete.cmd)

操作顺序Order of operations

  1. 安装 Windows 后,在登录屏幕出现之前,Windows 安装程序在 % WINDIR% \ 安装程序 \ 脚本 \ 目录 中搜索 setupcomplete.cmd 文件。After Windows is installed but before the logon screen appears, Windows Setup searches for the SetupComplete.cmd file in the %WINDIR%\Setup\Scripts\ directory.

  2. 如果找到 setupcomplete.cmd 文件,Windows 安装程序将运行该脚本。If a SetupComplete.cmd file is found, Windows Setup runs the script. Windows 安装程序将操作记录在 C: \ Windows \ Panther \ UnattendGC \ setupact.log 文件中。Windows Setup logs the action in the C:\Windows\Panther\UnattendGC\Setupact.log file.

    安装程序在执行 setupcomplete.cmd 后,不验证脚本中的任何退出代码或错误级别。Setup does not verify any exit codes or error levels in the script after it executes SetupComplete.cmd.

    警告 您无法重新启动系统并恢复运行 setupcomplete.cmdWarning You cannot reboot the system and resume running SetupComplete.cmd. 不应通过添加命令(如 shutdown) 来重新启动系统。You should not reboot the system by adding a command such as shutdown -r. 这会使系统处于错误的状态。This will put the system in a bad state.

  3. 如果计算机在安装过程中加入域,则在 setupcomplete.cmd 完成之前,域中定义的组策略不会应用到计算机。If the computer joins a domain during installation, the Group Policy that is defined in the domain is not applied to the computer until Setupcomplete.cmd is finished. 这是为了确保组策略配置活动不会影响脚本。This is to make sure that the Group Policy configuration activity does not interfere with the script.

如果 Windows 安装程序 (ErrorHandler 遇到错误,请运行脚本) Run a script if Windows Setup encounters a fatal error (ErrorHandler.cmd)

如果同时安装多个系统,则此脚本非常有用。This script is useful when you're installing many systems at the same time. 这有助于检测 Windows 安装程序期间发生错误的时间。This helps you detect when an error occurs during Windows Setup. 在此过程中,安装程序会自动运行一个脚本,该脚本可包含自定义命令或操作来解决错误的原因。When it does, Setup automatically runs a script that can contain custom commands or actions to address the cause of the error.

如果 Windows 安装程序遇到致命错误,无法完成安装,则 Windows 安装程序会在以下目录中搜索命令脚本: % WINDIR% \ 安装程序 \ 脚本 \ ErrorHandlerIf Windows Setup encounters a fatal error and is prevented from completing the installation, Windows Setup searches for a command script in the following directory: %WINDIR%\Setup\Scripts\ErrorHandler.cmd. 将发生两个操作之一,具体取决于是否找到该脚本。One of two actions will occur, depending on whether the script is found.

  • 如果未找到该脚本,则会显示带有错误文本的对话框。If the script is not found, a dialog box is displayed with the error text. 在 Windows 安装程序退出之前,用户必须关闭该对话框。A user must dismiss the dialog box before Windows Setup exits.
  • 如果找到该脚本,则会同步执行该脚本。If the script is found, the script executes synchronously. 不会显示对话框或错误文本。No dialog box or error text is displayed. ErrorHandler 脚本完成运行后,Windows 安装程序退出。After the ErrorHandler.cmd script has finished running, Windows Setup exits.

根据 Windows 安装程序的阶段,计算机将返回到从中执行 Windows 安装程序的环境,例如操作系统的早期版本或 (Windows PE) 的 Windows 预安装环境。Depending on the phase of Windows Setup, the computer will return to the environment from which Windows Setup was executed, such as an earlier version of the operating system or Windows Preinstallation Environment (Windows PE), for example.

有时 Windows 安装程序会遇到多个错误并多次运行 ErrorHandler.cmd 脚本。There may be instances when Windows Setup encounters more than one error and runs the ErrorHandler.cmd script more than once. 开发 ErrorHandler 的代码时,请确保可以多次运行此脚本。When developing the code for ErrorHandler.cmd, make sure that you can run this script multiple times.

若要使用 ErrorHandler,你可以执行以下任一操作:To use ErrorHandler.cmd, you can do either of the following:

  • 装载映像,并将其添加到 % WINDIR% \ 安装 \ 脚本 \ ErrorHandler 中的映像。Mount the image, and add it to the image, in %WINDIR%\Setup\Scripts\ErrorHandler.cmd. 卸载映像。Unmount the image.

    - 或 --or-

  • ErrorHandler 添加到临时文件位置 (例如,使用 C: \ Temp \ ErrorHandler) ,然后使用 /m 选项运行 Windows 安装程序。Add ErrorHandler.cmd to a temporary file location (for example, C:\Temp\ErrorHandler.cmd), and then run Windows Setup using the /m option.

    Setup /m:C:\Temp
    

    若要了解详细信息,请参阅 Windows 安装程序 Command-Line 选项To learn more, see Windows Setup Command-Line Options.

相关主题Related topics

Windows 安装程序技术参考Windows Setup Technical Reference

从 DVD 启动Boot from a DVD

将配置集用于 Windows 安装程序Use a Configuration Set with Windows Setup

部署自定义映像Deploy a Custom Image

使 Windows 启动进入审核模式或 OOBEBoot Windows to Audit Mode or OOBE

在 Windows 安装程序期间将设备驱动程序添加到 WindowsAdd Device Drivers to Windows During Windows Setup