分类 默认分类 下的文章

每次都搜,第一个URL又经常不是准确信息。

0000操作已成功完成。
0001错误的函数。
0002系统找不到指定的文件。
0003系统找不到指定的路径。
0004系统无法打开文件。
0005拒绝访问。
0006句柄无效。
0007存储区控制块已损坏。
0008可用的存储区不足,无法执行该命令。
0009存储区控制块地址无效。
0010环境错误。

0011试图使用不正确的格式加载程序。
0012访问代码无效。
0013数据无效。
0014可用的存储区不足,无法完成该操作。
0015系统找不到指定的驱动器。
0016无法删除该目录。
0017系统无法将文件移到其他磁盘驱动器上。
0018没有其他文件。
0019媒体写保护。
0020系统找不到指定的设备。

0021设备尚未准备好。
0022设备无法识别该命令。
0023数据错误(循环冗余检查)。
0024程序发出命令,但是该命令的长度错误。
0025驱动器在磁盘上无法定位指定的区域或磁道。
0026无法访问指定的磁盘或软盘。
0027驱动器找不到所请求的扇区。
0028打印机缺纸。
0029系统无法写入指定的设备。
0030系统无法读取指定的设备。

0031与系统连接的设备不能正常运转。
0032其他进程正使用该文件,因此现在无法访问。
0033另一进程已锁定该文件的某一部分,因此现在无法访问。
0034驱动器中的软盘不正确。请将%2(卷标序列号:%3)插入驱动器%1。
0036打开共享的文件太多。
0038已到达文件结尾。
0039磁盘已满。
0050不支持此网络请求。

0051远程计算机无法使用。
0052网络中存在重名。
0053找不到网络路径。
0054网络正忙。
0055指定的网络资源或设备已不可用。
0056已经达到网络命令的极限。
0057网络适配器出现错误。
0058指定的服务器无法执行所请求的操作。
0059网络出现意外错误。
0060远程适配器不兼容。

0061打印机队列已满。
0062服务器上没有存储等待打印的文件的空间。
0063已经删除等候打印的文件。
0064指定的网络名无法使用。
0065拒绝访问网络。
0066网络资源类型错误。
0067找不到网络名。
0068已超过本地计算机网络适配器卡的名称极限。
0069已超过网络BIOS会话的极限。
0070远程服务器已经暂停或者正在启动过程中。

0071由于该计算机的连接数目已达到上限,此时无法再连接到该远程计算机。
0072指定的打印机或磁盘设备已经暂停。
0080该文件存在。
0082无法创建该目录或文件。
0083INT24失败。
0084处理该请求的存储区不可用。
0085正在使用该本地设备名。
0086指定的网络密码不正确。
0087参数错误。
0088网络出现写入错误。
0089此时系统无法启动其他进程。
0100无法创建其他系统标志。

0101属于其他进程的专用标志。
0102标志已经设置,无法关闭。
0103无法再次设置该标志。
0104中断时无法请求专用标志。
0105此标志先前的所有权已终止。
0106请将软盘插入驱动器%1。
0107后续软盘尚未插入,程序停止。
0108磁盘正在使用或已由其他进程锁定。
0109管道已经结束。
0110系统无法打开指定的设备或文件。

0111文件名太长。
0112磁盘空间不足。
0113没有其他可用的内部文件标识符。
0114目标内部文件标识符不正确。
0117该应用程序所运行的IOCTL调用不正确。
0118校验写入的开关参数值不正确。
0119系统不支持所请求的命令。
0120该系统上不支持此功能。

0121标记已超时。
0123文件名、目录名或卷标语法错误。
0124系统调用层不正确。
0125磁盘没有卷标。
0126找不到指定的模块。
0127找不到指定的过程。
0128没有要等候的子进程。
0129模式下运行。
0130试图使用操作(而非原始磁盘I/O)的已打开磁盘分区的文件句柄。

0131试图将文件指针移至文件开头之前。
0132无法在指定的设备或文件中设置文件指针。
0133对于包含已连接驱动器的驱动器,不能使用JOIN或SUBST命令。
0134试图在已经连接的驱动器上使用JOIN或SUBST命令。
0135试图在已经替换的驱动器上使用JOIN或SUBST命令。
0136系统试图删除尚未连接的驱动器的JOIN。
0137系统试图删除尚未替换的驱动器的替换项。
0138系统试图将驱动器连接到已连接的驱动器下的目录。
0139系统试图将驱动器替换成已替换的驱动器下的目录。
0140系统试图将驱动器连接到已替换的驱动器的一个目录中。

0141系统试图将驱动器替换成到已连接的驱动器下的目录。
0142此时系统无法运行JOIN或SUBST。
0143系统无法将驱动器连接到或替换成同一驱动器下的目录。
0144此目录不是该根目录的子目录。
0145该目录未清空。
0146指定的路径已经在替换中使用。
0147资源不足,无法执行该命令。
0148此时无法使用指定的路径。
0149试图连接或替换某个驱动器目录,该驱动器上的某个目录是上一次替换的目标目录。
0150CONFIG.SYS文件未指定系统跟踪信息,或禁止跟踪。

0151DosMuxSemWait的指定信号事件的数目不正确。
0152DosMuxSemWait没有运行;已经设置太多的标志。
0153DosMuxSemWait列表不正确。
0154输入的卷标超过目标文件系统的标号字符长度极限。
0155无法创建其他线程。
0156接收进程拒绝该信号。
0157已经放弃该区域,因此无法锁定。
0158该区域已经解除锁定。
0159线程标识符的地址错误。
0160传到DosExecPgm的参数字符串错误。

0161指定的路径无效。
0162信号已挂起。
0164系统无法创建其他线程。
0167无法锁定文件的范围。
0170所要求的资源正在使用中。
0173锁定请求对于提供的取消区域不重要。
0174文件系统不支持到锁定类型的自动更改。
0180系统检测到错误的区域号码。

0182操作系统无法运行%1。
0183不能创建已经存在的文件。
0186传送的标志不正确。
0187找不到指定的系统信号名称。
0188操作系统无法运行%1。
0189操作系统无法运行%1。
0190操作系统无法运行%1。

0191无法在Win32模式下运行%1。
0192操作系统无法运行%1。
0193%1不是有效的Win32应用程序。
0194操作系统无法运行%1。
0195操作系统无法运行%1。
0196操作系统无法运行此应用程序。
0197当前无法配置操作系统运行此应用程序。
0198操作系统无法运行%1。
0199操作系统无法运行此应用程序。
0200代码段应小于64K。

0201操作系统无法运行%1。
0202操作系统无法运行%1。
0203系统找不到输入的环境选项。
0205在命令子树中的进程没有信号句柄。
0206文件名或扩展名太长。
0207环2堆栈正在使用中。
0208输入的全局文件名字符*或?不正确,或指定的全局文件名字符太多。
0209所发送的信号不正确。
0210无法设置信号处理程序。

0212区域已锁定,无法重新分配。
0214附加到此程序或动态链接模块的动态链接模块太多。
0215无法嵌套调用LoadModule。
0216图像文件%1有效,但不适用于本机类型。
0230管道状态无效。
0231所有的管道实例都处于忙状态。
0232管道正在关闭。
0233在管道的另一端没有进程。
0234有更多可用的数据。
0240已取消会话。

0254指定的扩展属性名无效。
0255扩展属性不一致。
0258等待操作过时。
0259没有其他可用数据。
0266无法使用复制功能。
0267目录名无效。
0275扩展属性不匹配缓冲区。
0276所装载的文件系统上的扩展属性文件已被损坏。
0277扩展属性表格文件已满。
0278指定的扩展属性句柄无效。

0282安装的文件系统不支持扩展属性。
0288试图释放不属于调用者的多路同步信号。
0298信号投递的次数太多。
0299仅完成部分ReadProcessMemory或WriteProcessMemory请求。
0300操作锁定请求被拒绝。
0301系统接收了一个无效的操作锁定确认。
0317在%2的消息文件中,系统无法找到消息号为0x%1的消息文本。
0487试图访问无效地址。
0534运算结果超过32位。
0535该管道的另一方有一进程。
0536等候进程打开管道的另一端。

0994拒绝对扩展属性的访问。
0995由于线程退出或应用程序的要求,I/O操作异常终止。
0996重叠的I/O事件不处于已标记状态。
0997正在处理重叠的I/O操作。
0998对内存位置的无效访问。
0999执行页内操作出错。

1001递归太深;堆栈溢出。
1002窗口无法用来发送消息。
1003无法完成此项功能。
1004标志无效。
1005卷不包含已识别的文件系统。请确认所有需要的文件系统驱动程序都已经加载,而且卷没有任何损坏。
1006某文件的卷已在外部改变,因而打开的文件不再有效。
1007要求的操作无法以全屏幕模式执行。
1008试图引用并不存在的符号。
1009配置注册表数据库已损坏。
1010配置注册表主键无效。

1011无法打开配置注册表主键。
1012无法读取配置注册表主键。
1013无法写入配置注册表主键。
1014必须使用日志文件或其他副本来恢复注册表数据库中的某个文件。恢复成功。
1015注册表已损坏。可能是一个包含注册表数据文件的结构已损坏,也可能内存中该文件的系统映像已损坏,或者因为备份副本(或日志)不存在(或损坏)导致无法恢复该文件。
1016由注册表引起的I/O操作发生了不可恢复的错误。注册表将不能读取、写出或刷新包含注册表系统映像的其中一个文件。
1017系统试图将文件加载或还原到注册表中,但是,指定的文件不是注册表文件格式。
1018试图在注册表键(已经标记为删除)中完成的操作非法。
1019系统无法在注册表日志文件中分配所需的空间。
1020无法在已经有子键或键值的注册表项中创建符号链接。
1021在易失的父键下不能创建固定的子键。
1022通知的更改请求已经完成,并且返回信息还没有被送到调用者的缓冲区中。调用者需要列举所有文件以找到改动的内容。

1051已将停止控制发送给与其他运行服务相关的服务。
1052所要求的控制对此服务无效。
1053服务没有及时地响应启动或控制请求。
1054无法为该服务创建线程。
1055服务数据库已锁定。
1056该服务的实例已在运行。
1057帐户名无效或者不存在,或者指定帐户名的密码无效。
1058服务无法启动,可能因为被禁用,也可能因为没有关联的可用设备。
1059已经指定了循环服务的从属关系。
1060指定的服务不是所安装的服务。

1061该服务此时无法接收控制消息。
1062服务尚未启动。
1063服务进程无法连接到服务控制程序。
1064处理控制请求时,服务出现意外情况。
1065指定的数据库不存在。
1066服务返回服务特定的错误码。
1067进程意外地终止。
1068无法启动从属服务或组。
1069由于登录失败,没有启动服务。
1070启动后,服务保持在启动挂起状态。

1071指定的服务数据库锁定无效。
1072指定的服务已经标记为删除。
1073指定的服务已经存在。
1074系统当前正以上一次运行成功的配置运行。
1075从属服务不存在,或已经标记为删除。
1076已接受使用当前引导作为最后的有效控制设置。
1077自从上一次启动以后,没有再次启动过该服务。
1078该名称已经用作服务名或服务显示名。
1079此服务的帐户不同于运行于同一进程上的其它服务的帐户。
1080只能为Win32服务设置失败操作,不能为驱动程序设置。
1081这个服务所运行的进程和服务控制管理器相同。所以,如果服务进程意外中止的话,服务控制管理器无法进行任何操作。
1082这个服务没有设置恢复程序。
1083配置成在该可执行程序中运行的这个服务不能执行该服务。
1100已经到达磁带的物理尽头。

1101磁带访问到文件标记。
1102到达磁带或分区首部。
1103磁带访问到文件组的末尾。
1104磁带上没有其他数据。
1105磁带无法分区。
1106访问多重卷分区的新磁带时,当前的区块大小不正确。
1107加载磁带时,找不到磁带分区信息。
1108无法锁定媒体退出功能。
1109无法卸载媒体。
1110驱动器中的媒体已经更改。

1111已经复位I/O总线。
1112驱动器中没有媒体。
1113在目标多字节代码页中不存在对单码字符的映射。
1114动态链接库(DLL)初始化例程失败。
1115正在关闭系统。
1116无法终止系统关机,因为没有进行中的关机操作。
1117由于I/O设备出现错误,无法运行该请求。
1118串行设备初始化失败。将卸载串行驱动程序。
1119无法打开正与其他设备共享中断请求(IRQ)的设备。至少有一个使用该IRQ的设备已经打开。
1120由于再次写入串行口,串行I/O操作已结束。(IOCTL_SERIAL_XOFF_COUNTER为零。)

1121由于超时,串行I/O操作已结束。(IOCTL_SERIAL_XOFF_COUNTER未达到零。)
1122在软盘上找不到标识符地址标记。
1123软盘扇区标识符字段与软盘控制器磁道地址不匹配。
1124软盘控制器报告软盘驱动程序不能识别的错误。
1125软盘控制器返回的结果和注册的不一致。
1126访问硬盘时,再校准操作失败,再试一次后也无法操作。
1127访问硬盘时,磁盘操作失败,再试一次后仍没有作用。
1128访问硬盘时,需要重启动磁盘控制器,但仍未成功。
1129磁带已卷到尽头。
1130可用的服务器存储区不足,无法执行该命令。

1131检测到潜在的死锁情况。
1132指定的基址或文件偏移量没有正确对齐。
1140试图更改系统电源状态的操作被另一应用程序或驱动程序禁止。
1141系统BIOS无法更改系统电源状态。
1142试图在一文件上创建超过系统允许数额的链接。
1150指定的程序需要新的Windows版本。

1151指定的程序不是Windows或MS-DOS程序。
1152无法启动指定程序的多个实例。
1153指定的程序是为Windows的早期版本编写的。
1154运行此应用程序所需的某个库文件已损。
1155没有应用程序与该操作中所指定的文件关联。
1156将命令发送到应用程序时出现错误。
1157找不到运行此应用程序所需的某个库文件。
1158当前进程已使用了Window管理器对象的系统允许的所有句柄。
1159消息只能与同步操作一起使用。
1160指出的源元素没有媒体。

1161指出的目标元素已包含媒体。
1162指出的元素不存在。
1163指出的元素是未显示的存储资源的一部分。
1164指出的设备需要重新初始化,因为硬件有错误。
1165设备显示在尝试进一步操作之前需要清除。
1166设备显示它的门仍是打开状态。
1167设备没有连接。
1168找不到元素。
1169索引中没有同指定项相匹配的项。
1170在对象上不存在指定的属性集。

1171传递到GetMouseMovePoints的点不在缓冲区中。
1172跟踪(工作站)服务没运行。
1173找不到卷ID。
1175无法删除要被替换的文件。
1176无法将替换文件移到要被替换的文件。要被替换的文件保持原来的名称。
1177无法将替换文件移到要被替换的文件。要被替换的文件已被重新命名为备份名称。
1178卷更改记录被删除。
1179卷更改记录服务不处于活动中。
1180找到一份文件,但是可能不是正确的文件。
1181日志项已从日志中删除。
1200指定的设备名无效。

1201设备当前虽然未连接,但它是记忆连接。
1202试图记起已经记住的设备。
1203网络供应商不接受给定的网络路径。
1204指定的网络供应商名无效。
1205无法打开网络连接配置文件。
1206网络连接配置文件已损坏。
1207无法列举非包容类。
1208出现扩展错误。
1209指定组名的格式无效。
1210指定计算机名的格式无效。

1211指定事件名的格式无效。
1212指定域名的格式无效。
1213指定服务名的格式无效。
1214指定网络名的格式无效。
1215指定共享名的格式无效。
1216指定密码的格式无效。
1217指定的邮件名无效。
1218指定邮件目的地的格式无效。
1219所提供的凭据与现有凭据设置冲突。
1220试图与网络服务器建立会话,但目前与该服务器建立的会话太多。

1221网络上的其他计算机已经使用该工作组或域名。
1222网络不存在或者没有启动。
1223用户已经取消该操作。
1224所要求的操作无法在已经打开用户映射区域的文件中运行。
1225远程系统拒绝网络连接。
1226已经关闭网络连接。
1227网络传输的终点已经有一个地址与其关联。
1228网络终点尚未与地址关联。
1229试图在不存在的网络连接中操作。
1230试图在活动的网络连接上进行无效操作。

1231不能访问网络位置。有关网络疑难解答的信息,请参阅Windows帮助。
1232不能访问网络位置。有关网络疑难解答的信息,请参阅Windows帮助。
1233不能访问网络位置。有关网络疑难解答的信息,请参阅Windows帮助。
1234远程系统的目标网络端点没有运行任何服务。
1235该请求已经终止。
1236本地系统已经终止网络连接。
1237无法完成操作。请再试一次。
1238无法创建到该服务器的连接,因为已经到达了该帐户同时连接的最大数目。
1239试图在该帐户未授权的时间内登录。
1240尚未授权此帐户从该站登录网络。

1241网络地址无法用于要求的操作。
1242服务已经注册。
1243指定的服务不存在。
1244由于尚未验证用户身份,无法执行要求的操作。
1245由于用户尚未登录网络,无法运行要求的操作。指定的服务不存在。
1246继续工作。
1247完成初始化操作后,试图再次运行初始化操作。
1248没有其他本地设备。
1249指定的站点不存在。
1250具有指定名称的域控制器已经存在。

1251只有连接到服务器上时,才支持该操作。
1252即使没有改动,组策略框架也应该调用扩展。
1253指定的用户没有一个有效的配置文件。
1254MicrosoftSmallBusinessServer不支持此操作。
1300不是对所有的调用方分配引用特权。

1301帐户名与安全标识符之间的映射未完成。
1302没有为该帐户明确地设置系统配额限制。
1303没有可用的密钥。返回已知的密钥。
1304密码太复杂,无法转换成LANManager密码。返回的LANManager密码是空字符串。
1305修订级别未知。
1306表示两个修订级别不兼容。
1307无法将此安全标识符指定为该对象的拥有者。
1308无法将此安全标识符指定为主要的对象组。
1309当前并未模拟客户的线程试图操作模拟令牌。
1310不可以禁用该组。

1311目前没有可用的登录服务器处理登录请求。
1312指定的登录会话不存在。该会话可能已终止。
1313指定的权限不存在。
1314客户不保留请求的权限。
1315提供的名称不是正确的帐户名称格式。
1316指定的用户已经存在。
1317指定的用户不存在。
1318指定的组已经存在。
1319指定的组不存在。
1320或者指定的用户帐户已经是某个特定组的成员,或者也可能指定的组非空而不能被删除。

1321指定的用户帐户不是所指定组帐户的成员。
1322上次保留的管理帐户无法关闭或删除。
1323无法更新密码。所输入的密码不正确。
1324无法更新密码。所提供的新密码包含不可用于密码的值。
1325无法更新密码。为新密码提供的值不符合字符域的长度、复杂性或历史要求。
1326登录失败:用户名未知或密码错误。
1327登录失败:用户帐户限制。
1328登录失败:违反帐户登录时间限制。
1329登录失败:禁止用户登录到该计算机上。
1330登录失败:指定的帐户密码已过期。

1331登录失败:当前禁用帐户。
1332未完成帐户名与安全性标识符之间的映射。
1333一次请求的本地用户标识符(LUID)太多。
1334没有其他可用的本地用户标识符(LUID)。
1335对这个特定使用来说,安全标识符的子部分是无效的。
1336访问控制清单(ACL)结构无效。
1337安全标识符结构无效。
1338安全描述符结构无效。
1340无法创建继承的访问控制列表(ACL)或访问控制项目(ACE)。

1341当前已禁用服务器。
1342当前已启用服务器。
1343所提供的值是无效的标识符授权值。
1344没有更多的内存用于更新安全信息。
1345指定的属性无效,或指定的属性与整个组的属性不兼容。
1346或者没有提供所申请的模仿级别,或者提供的模仿级别无效。
1347无法打开匿名级安全性符号。
1348所请求的验证信息类别无效。
1349该类符号不能以所尝试的方式使用。
1350无法在没有相关安全性的对象上运行安全操作。

1351未能从域控制器读取配置信息,或者是因为机器不可使用,或者是访问被拒绝。
1352安全帐户管理程序(SAM)或本地安全颁发机构(LSA)服务器状态不正确,所以无法运行安全操作。
1353域处于执行安全操作的错误状态。
1354该操作只能在域的主域控制器中执行。
1355指定的域不存在或联系不上。
1356指定的域已经存在。
1357试图超过每个服务器域数目的极限。
1358由于严重的媒体错误或磁盘的数据结构损坏,无法完成所请求的操作。
1359发生内部错误。
1360通用的访问类型包含在访问掩码中,该掩码已经映射为非通用类型。

1361安全性描述符的格式错误(绝对或自相关)。
1362请求的操作只准登录进程使用。该调用过程并未被记录为登录进程。
1363无法用已经使用的标识符来启动新的登录会话。
1364指定的确认数据包未知。
1365登录会话的状态与请求的操作不一致。
1366登录会话标识符正在使用中。
1367登录请求包含无效的登录类型值。
1368在使用命名管道读取数据之前,无法经由该管道模拟。
1369注册表子树的事务状态与所请求的操作不兼容。
1370突发的内部安全性数据库故障。

1371无法在内部帐户下运行该操作。
1372无法在该内部特定组中运行该操作。
1373无法在该内部特定用户中运行该操作。
1374因为该组当前是用户的主要组,所以不能从此组中删除用户。
1375该符号已作为主要符号使用。
1376指定的本地组不存在。
1377指定的帐户名不是本地组的成员。
1378指定的帐户名已经是本地组的成员。
1379指定的本地组已经存在。
1380登录失败:用户在本计算机上没有被授与所需注册类型。

1381超过了可以存储在单个系统中的最大机密限制。
1382机密的长度超过了最大允许值。
1383本地安全授权数据库包含内部不一致的错误。
1384登录时,用户的安全性上下文累积太多的安全标识符。
1385登录失败:用户在本计算机上没有被授与所需注册类型。
1386经交叉加密的密码必须更改用户密码。
1387成员不存在,因此无法将其添加到本地组或从中删除。
1388新成员的帐户类型有误,因此无法将其添加到本地组。
1389指定的安全标识符太多。
1390经交叉加密的密码必须更改该用户密码。

1391表示ACL没有可继承的组件。
1392文件或目录已损坏,无法读取数据。
1393磁盘结构已损坏,无法读取数据。
1394指定的登录会话没有用户会话密钥。
1395正在访问的服务允许特定数目的连接。因为连接的数目已达到服务可接受的数目,所以此时无法创建新的服务连接。
1396登录失败:该目标帐户名称不正确。
1397相互身份验证失败。该服务器在域控制器的密码过期。
1398在客户机和服务器之间有一个时间差。
1400窗口句柄无效。

1401菜单句柄无效。
1402光标句柄无效。
1403加速键表的句柄无效。
1404挂接句柄无效。
1405多重窗口位置结构句柄无效。
1406无法创建最上层的子窗口。
1407找不到窗口类。
1408窗口无效;属于其他线程。
1409已经注册热键。
1410类已经存在。

1411类不存在。
1412类窗口仍打开着。
1413索引无效。
1414图标句柄无效。
1415使用私人对话框窗口字。
1416找不到列表框标识符。
1417找不到任何通配符。
1418线程没有打开剪贴板。
1419尚未注册热键。
1420该窗口不是有效的对话框窗口。

1421找不到控制标识符。
1422由于没有编辑控制,因此该组合框的消息无效。
1423窗口不是组合框。
1424高度必须小于256。
1425设备上下文(DC)句柄无效。
1426挂接过程类型无效。
1427挂接过程无效。
1428不能在无模块句柄的情况下设置非本地的挂接。
1429只能全局设置该挂接过程。
1430已安装日记挂接过程。

1431未安装挂接过程。
1432单选列表框的消息无效。
1433LB_SETCOUNT发送到活动的列表框。
1434该列表框不支持制表符。
1435无法破坏由其他线程所创建的对象。
1436子窗口不能有菜单。
1437窗口没有系统菜单。
1438消息框样式无效。
1439系统范围内的(SPI_*)的参数无效。
1440屏幕已经锁定。

1441多重窗口位置结构中所有窗口句柄必须具有相同的父窗口。
1442窗口不是子窗口。
1443GW_*命令无效。
1444线程标识符无效。
1445无法处理非多文档接口(MDI)窗口的消息。
1446弹出式菜单已激活。
1447窗口没有滚动条。
1448滚动条范围不能大于MAXLONG。
1449无法以指定的方式显示或关闭窗口。
1450系统资源不足,无法完成所请求的服务。

1451系统资源不足,无法完成所请求的服务。
1452系统资源不足,无法完成所请求的服务。
1453配额不足,无法完成请求的服务。
1454配额不足,无法完成请求的服务。
1455页面交换文件太小,无法完成此项操作。
1456找不到菜单项。
1457键盘布局句柄无效。
1458不允许使用挂钩类型。
1459该操作需要交互式窗口工作站。
1460由于超时时间已过,该操作返回。
1461无效监视器句柄。
1500事件日志文件已损坏。
1501无法打开事件日志文件,因此无法启动事件记录服务。
1502事件日志文件已满。
1503事件日志文件在两次读取操作间已发生变化。
1601无法访问Windows安装服务。请与技术支持人员联系,确认Windows安装服务是否注册正确。
1602用户取消了安装。
1603安装时发生严重错误。
1604安装已挂起,未完成。
1605这个操作只对当前安装的产品有效。
1606功能ID未注册。
1607组件ID未注册。
1608未知属性。
1609句柄处于不正确的状态。
1610这个产品的配置数据已损坏。请与技术支持人员联系。

1611组件限制语不存在。
1612这个产品的安装来源无法使用。请验证来源是否存在,是否可以访问。
1613Windows安装服务无法安装这个安装程序包。您必须安装含有Windows安装服务新版本的WindowsServicePark。
1614产品已卸载。
1615SQL查询语法不正确或不被支持。
1616记录字符域不存在。
1617设备已被删除。
1618正在进行另一个安装操作。请在继续这个安装操作之前完成那个操作。
1619未能打开这个安装程序包。请验证程序包是否存在,是否可以访问;或者与应用程序供应商联系,验证这是否是有效的Windows安装程序包。
1620未能打开这个安装程序包。请与应用程序供应商联系,验证这是否是有效的Windows安装程序包。

1621启动Windows安装服务用户界面时有错误。请与技术支持人员联系。
1622打开安装日志文件时出错。请验证指定的日志文件位置是否存在,是否可以写入。
1623安装程序包的语言不受系统支持。
1624应用变换时出错。请验证指定的变换路径是否有效。
1625系统策略禁止这个安装。请与系统管理员联系。
1626无法执行函数。
1627执行期间,函数出了问题。
1628指定了无效的或未知的表格。
1629提供的数据类型不对。
1630这个类型的数据不受支持。

1631Windows安装服务未能启动。请与技术支持人员联系。
1632临时文件夹已满或无法使用。请验证临时文件夹是否存在,是否可以写入。
1633这个处理器类型不支持该安装程序包。请与产品供应商联系。
1634组件没有在这台计算机上使用。
1635无法打开修补程序包。请验证修补程序包是否存在,是否可以访问;或者与应用程序供应商联系,验证这是否是有效的Windows安装修补程序包。
1636无法打开修补程序包。请与应用程序供应商联系,验证这是否是有效的Windows安装修补程序包。
1637Windows安装服务无法处理这个修补程序包。您必须安装含有Windows安装服务新版本的WindowsServicePack。
1638已安装这个产品的另一个版本。这个版本的安装无法继续。要配置或删除这个产品的现有版本,请用“控制面板”上的“添加/删除程序”。
1639无效的命令行参数。有关详细的命令行帮助,请查阅Windows安装服务的SDK。
1640在终端服务远程会话期间,只有管理员有添加、删除或配置服务器软件的权限。如果您要在服务器上安装或配置软件,请与网络管理员联系。
1641要求的操作已成功结束。要使改动生效,必须重新启动系统。
1642Windows安装服务无法安装升级修补程序,因为被升级的程序丢失,或者升级修补程序将更新此程序的其他版本。请确认要被升级的程序在您的计算机上且您的升级修补程序是正确的。
1700串绑定无效。

1701绑定句柄的类型错误。
1702绑定句柄无效。
1703不支持RPC协议顺序。
1704RPC协议序列无效。
1705字符串的全球唯一标识符(UUID)无效。
1706终点的格式无效。
1707网络地址无效。
1708未找到终点。
1709超时设置值无效。
1710找不到该对象的全球唯一标识符(UUID)。

1711该对象的全球唯一标识符(UUID)已经注册。
1712这一类型的全球唯一标识符(UUID)已经注册。
1713RPC服务器正在监听。
1714尚未注册协议顺序。
1715RPC服务器不处于监听状态。
1716管理程序的类型未知。
1717接口未知。
1718没有绑定。
1719没有协议序列。
1720无法创建终点。

1721资源不足,无法完成该操作。
1722RPC服务器无法使用。
1723RPC服务器太忙,无法完成此项操作。
1724网络选项无效。
1725该线程中不存在活动的远程过程调用。
1726远程过程调用失败。
1727远程过程调用失败并且无法执行。
1728远程过程调用(RPC)协议出现错误。
1730RPC服务器不支持传输语法。

1732不支持这种类型的全球唯一标识符。
1733标识无效。
1734数组边界无效。
1735绑定类型中不包含项目名。
1736名称语法无效。
1737不支持这种命名语法。
1739没有可用的网络地址,无法创建全球唯一标识符(UUID)。
1740终结点重复。

1741身份验证类型未知。
1742调用次数的上限太小。
1743字符串太长。
1744找不到RPC协议序列。
1745过程号超出范围。
1746此次绑定不包含任何身份验证信息。
1747身份验证服务未知。
1748身份验证级别未知。
1749安全描述符无效。
1750身份验证服务未知。

1751项目无效。
1752服务器的终结点无法执行此项操作。
1753终点的映射器没有更多的终点可用。
1754没有导出任何接口。
1755项目名不完整。
1756版本选项无效。
1757没有其他成员。
1758可以导出全部内容。
1759未找到接口。
1760项目已经存在。

1761项目找不到。
1762名称服务不可用。
1763网络地址集无效。
1764不支持请求的操作。
1765没有可供冒仿的安全性描述符。
1766远程过程调用(RPC)出现内部错误。
1767RPC服务器企图进行整除零运算。
1768RPC服务器出现寻址错误。
1769RPC服务器中的浮点运算造成被零除。
1770RPC服务器产生了浮点下溢错误。

1771RPC服务器产生了浮点上溢错误。
1772可用于自动句柄绑定的RPC服务器列表已经用完。
1773无法打开字符转换表文件。
1774包含字符转换表的文件小于512个字节。
1775在远程过程调用中,客户机向主机传送了一个空的描述体句柄。
1777远程过程调用中的描述体句柄发生变化。
1778发送到远程过程调用的绑定句柄不匹配。
1779占位程序无法获得远程过程调用的句柄。
1780将空的参考指针发送给占位程序。

1781列举值超出范围。
1782字节数目太小。
1783占位程序接收到错误数据。
1784所提供的用户缓冲区对所申请的操作无效。
1785无法识别磁盘媒体。它可能还未格式化。
1786工作站没有信任密码。
1787服务器上的安全数据库中没有该工作站信任关系的计算机帐户。
1788建立主域和受托域间的信任关系失败。
1789建立工作站和主域间的信任关系失败。
1790网络登录失败。

1791该线程执行过程中已经进行了远程过程调用。
1792试图登录网络,但网络登录服务尚未启动。
1793用户帐户已到期。
1794重定向程序正在使用,无法卸载。
1795已经安装所指定的打印机驱动程序。
1796指定的端口未知。
1797打印机驱动程序未知。
1798打印处理程序未知。
1799指定的分隔符文件无效。
1800指定的优先级无效。

1801打印机名无效。
1802打印机已经存在。
1803打印机命令无效。
1804指定的数据类型无效。
1805指定的环境无效。
1806没有其他绑定。
1807使用的帐户是跨网络的信任帐户。请使用全局用户帐户或本地用户帐户来访问此服务器。
1808所使用的帐户是计算机帐户。请使用全局用户帐户或本地用户帐户来访问该服务器。
1809使用的帐户是服务器信任帐户。请使用全局用户帐户或本地用户帐户来访问该服务器。
1810指定的域名或安全标识符与域的信任信息不一致。

1811服务器正在使用中,无法卸载。
1812指定的映像文件不包含资源部分。
1813在映像文件中找不到指定的资源类型。
1814在映像文件中找不到指定的资源名称。
1815在映像文件中找不到指定的资源语言ID。
1816可用的配额不足,无法执行该命令。
1817没有已注册的接口。
1818远程过程调用被取消。
1819绑定句柄不包含所有需要的信息。
1820远程调用过程中发生通讯失败。

1821所需的身份验证级别不被支持。
1822主要的名称没有注册。
1823指定的错误不是有效的WindowsRPC错误代码。
1824已分配仅在本机上有效的UUID。
1825产生了特定的安全包错误。
1826没有取消线程。
1827在编码/解码处理时的操作无效。
1828序列化软件包的版本不兼容。
1829RPC占位程序的版本不兼容。
1830RPC管道对象无效或已损坏。

1831试图在RPC管道对象上进行无效操作。
1832不被支持的RPC管道版本。
1898找不到组成员。
1899无法创建终结点映射数据库条目。
1900对象的全球标识符(UUID)为空。

1901指定的时间无效。
1902指定的表单名无效。
1903指定的表单大小无效。
1904指定的打印机句柄正在等候处理
1905指定的打印机已经删除。
1906打印机的状态无效。
1907用户首次登录前,必须先更改其密码。
1908找不到该域的域控制器。
1909引用的帐户目前被锁定,可能无法登录。
1910没有发现指定的此对象导出者。

1911没有发现指定的对象。
1912没有发现指定的对象解析器。
1913一些待发数据仍停留在请求缓冲区内。
1914无效的异步远程过程调用句柄。
1915这个操作的异步RPC调用句柄不正确。
1916RPC管道对象已经关闭。
1917RPC调用在全部的管道都被处理之前完成。
1918没有其他可用的数据来自RPC管道。
1919这个机器没有可用的站点名。
1920系统无法访问此文件。

1921系统无法解析文件名。
1922项目不是所要的类型。
1923无法将所有对象的UUID导出到指定的项。
1924无法将接口导出到指定的项。
1925无法添加指定的配置文件项。
1926无法添加指定的配置文件元素。
1927无法删除指定的配置文件元素。
1928无法添加组元素。
1929无法删除组元素。
2000像素格式无效。

2001指定的驱动程序无效。
2002该操作的窗口样式或类属性无效。
2003不支持请求的图元文件操作。
2004不支持肭蟮淖徊僮鳌?nbsp;
2005不支持请求的剪辑操作。
2010指定的颜色管理模块无效。

2011指定的颜色文件配置无效。
2012找不到指定的标识。
2013所需的标识不存在。
2014指定的标识已经存在。
2015指定的颜色文件配置与任何设备都不相关。
2016找不到该指定的颜色文件配置。
2017指定的颜色空间无效。
2018图像颜色管理没有启用。
2019在删除该颜色转换时有一个错误。
2020指定的颜色转换无效。

2021指定的转换与位图的颜色空间不匹配。
2022指定的命名颜色索引在配置文件中不存在。
2108网络连接已成功,但需要提示用户输入一个不同于原始指定的密码。
2202指定的用户名无效。
2250网络连接不存在。

2401在这个网络连接上已存在打开的文件或未处理的请求。
2402活动的连接仍然存在。
2404设备正由活动进程使用,无法断开连接。

3000指定的打印监视程序未知。
3001指定的打印机驱动程序正在使用中。
3002找不到假脱机文件。
3003没有发出StartDocPrinter调用。
3004尚未发出AddJob调用。
3005指定的打印处理程序已经安装。
3006指定的打印监视程序已经安装。
3007该指定的打印监视器不具备所要求的功能。
3008指定的打印机监视器正在使用中。
3009当打印机有作业排成队列时此操作请求是不允许的。
3010请求的操作成功。只有重新启动系统,更改才会生效。

3011请求的操作成功。只有重新启动服务,更改才会生效。
3012找不到打印机。
4000WINS在处理命令时遇到执行错误。
4001无法删除本地的WINS。
4002从文件引入失败。
4003备份失败。以前执行过完整的备份吗?
4004备份失败。请检查备份数据库的目标目录。
4005名称在WINS数据库中不存在。
4006不允许进行未配置部分的复制。
4100DHCP客户获得一个在网上已被使用的IP地址。直到DHCP客户可以获得新的地址前,本地接口将被禁用。
4200WMI数据提供程序不能识别传来的GUID是否有效。

4201WMI数据提供程序无法识别传来的实例名是否有效。
4202WMI数据提供程序无法识别传来的数据项目标识符是否有效。
4203无法完成WMI请求,请重试一次。
4204找不到WMI数据提供程序。
4205WMI数据提供程序引用到一个未注册的实例组。
4206WMI数据块或事件通知已启用。
4207WMI数据块不再可用。
4208WMI数据服务无法使用。
4209WMI数据提供程序无法完成请求。
4210WMIMOF信息无效。

4211WMI注册信息无效。
4212WMI数据块或事件通知已禁用。
4213WMI数据项目或数据块为只读。
4214WMI数据项目或数据块不能更改。
6118该工作组的服务器列表当前不可用。
6200要正常运行,任务计划程序服务的配置必须在系统帐户中运行。单独的任务可以被配置成在其他帐户中运行。

7001指定的会话名无效。
7002指定的协议驱动程序无效。
7003在系统路径上找不到指定的协议驱动程序。
7004在系统路径上找不到指定的终端连接驱动程序。
7005不能为这个会话创建一个事件日志的注册键。
7006同名的一个服务已经在系统中存在。
7007在会话上一个关闭操作挂起。
7008没有可用的输出缓冲器。
7009找不到MODEM.INF文件。
7010在MODEM.INF中没有找到调制解调器名称。

7011调制解调器没有接受发送给它的指令。验证配置的调制解调器与连接的调制解调器是否匹配。
7012调制解调器没有响应发送给它的指令。验证该调制解调器是否接线正确并且打开了电源开关。
7013由于断开连接,载波检测失败或载波停止。
7014在要求的时间内没有发现拨号音。确定电话线连接正确并可使用。
7015在远程站点回叫时检测到了占线信号。
7016在回叫时远程站点上检测到了声音。
7017传输驱动程序错误

7022找不到指定的会话。
7023指定的会话名称已处于使用中。
7024由于终端连接目前正在忙于处理一个连接、断开连接、复位或删除操作,无法完成该请求的操作。
7025试图连接到其视频模式不受当前客户支持的会话。
7035应用程序尝试启动DOS图形模式。不支持DOS图形模式。
7037您的交互式登录权限已被禁用。请与您的管理员联系。
7038该请求的操作只能在系统控制台上执行。这通常是一个驱动程序或系统DLL要求直接控制台访问的结果。
7040客户未能对服务器连接消息作出响应。

7041不支持断开控制台会话。
7042不支持重新将一个断开的会话连接到控制台。
7044远程控制另一个会话的请求被拒绝。
7045拒绝请求的会话访问。
7049指定的终端连接驱动程序无效。
7050不能远程控制请求的会话。这也许是由于该会话被中断或目前没有一个用户登录。另外,您不能从该系统控制台远程控制一个会话或远程控制系统控制台。并且,您不能远程控制您自己的当前会话。

7051该请求的会话没有配置成允许远程控制。
7052连接到这个终端服务器的申请被拒绝。终端服务器客户许可证目前正在被另一个用户使用。请与系统管理员联系,获取一份新的终端服务器客户,其许可证号码必须是有效的、唯一的。
7053连接到这个终端服务器的申请被拒绝。还没有为这份终端服务器客户输入您的终端服务器客户许可证号码。请与系统管理员联系,为该终端服务器客户输入一个有效的、唯一的许可证号码。
7054系统已达到其授权的登录限制。请以后再试一次。
7055您正在使用的客户没有使用该系统的授权。您的登录请求被拒绝。
7056系统许可证已过期。您的登录请求被拒绝。

第1章:Uvicorn 简介

1.1 什么是 Uvicorn

Uvicorn 是一个 Python ASGI 服务器,用于运行支持异步协议的 Web 应用。它常见于 FastAPI、Starlette、Quart 等 ASGI 框架场景,也可以直接运行原生 ASGI 应用。

相比传统 WSGI 服务器,Uvicorn 面向异步 I/O 设计,支持 HTTP/1.1 与 WebSocket,并提供热重载、多进程、日志配置、代理头处理、HTTPS 等能力。

1.2 Uvicorn 的定位

开发阶段:本地启动 ASGI 应用,配合 --reload 实现代码热更新

  • 测试阶段:快速验证服务入口、接口行为和日志输出
  • 部署阶段:作为生产服务进程本身运行,或作为 Gunicorn / 反向代理体系中的一部分

1.3 核心特性

  • 支持 ASGI:适合异步 Python Web 应用
  • 启动方式灵活:支持命令行和代码调用两种方式
  • 配置完整:监听地址、协议栈、日志、超时、并发、TLS 都可配置
  • 支持多进程:可以通过 --workers 开启多个工作进程
  • 开发体验好:配合 watchfiles 时支持更细粒度的热重载

第2章:安装指南

2.1 基础安装

Uvicorn 发布在 PyPI,可安装最小依赖版本:

pip install uvicorn

最小安装通常会包含:

  • click:命令行接口支持
  • h11:纯 Python 的 HTTP/1.1 实现

2.2 标准增强安装

如果希望一次安装常用增强依赖,推荐使用标准扩展:

pip install "uvicorn[standard]"

uvicorn[standard] 通常会额外包含:

  • uvloop:高性能事件循环,性能更好,但不兼容 Windows
  • httptools:更高性能的 HTTP 解析器
  • websockets:WebSocket 支持
  • watchfiles:热重载文件监控
  • python-dotenv:支持 --env-file
  • PyYAML:支持 YAML 日志配置
  • colorama:Windows 终端彩色输出支持

2.3 什么时候装最小版,什么时候装标准版

  • 最小版:只想快速跑起来,或者部署环境强调依赖最少
  • 标准版:开发环境、本地调试、需要热重载、WebSocket 或更好的日志体验

对于大多数开发场景,建议直接使用标准版。

第3章:第一个 Uvicorn 应用

3.1 原生 ASGI 应用示例

创建 main.py:

async def app(scope, receive, send):
assert scope["type"] == "http"

body = b"Hello, Uvicorn!"

await send(
{
"type": "http.response.start",
"status": 200,
"headers": [
(b"content-type", b"text/plain; charset=utf-8"),
(b"content-length", str(len(body)).encode("ascii")),
],
}
)
await send(
{
"type": "http.response.body",
"body": body,
}
)

3.2 命令行启动

在项目根目录执行:

uvicorn main:app

这里的 main:app 表示:

  • main:Python 模块名,即 main.py
  • app:模块中的 ASGI 应用对象

默认监听:

  • 主机:127.0.0.1
  • 端口:8000

打开浏览器访问 http://127.0.0.1:8000 即可看到结果。

3.3 常用启动形式

指定主机和端口

uvicorn main:app --host 0.0.0.0 --port 9000

开发模式热重载

uvicorn main:app --reload

使用应用工厂

如果应用通过工厂函数返回:

def create_app():
return app

则启动命令为:

uvicorn --factory main:create_app

第4章:运行方式

4.1 命令行方式

Uvicorn 最常见的使用方式是直接通过命令行运行:

uvicorn main:app --host 127.0.0.1 --port 8000

适合场景:

  • 本地开发
  • 容器启动命令
  • 测试环境直接拉起服务

4.2 代码方式

如果要在 Python 代码中控制服务启动,可以使用 uvicorn.run():

import uvicorn

async def app(scope, receive, send):

...

if __name__ == "__main__":
uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info")

注意事项:

  • 如果要使用 reload=True 或 workers > 1,官方建议把 uvicorn.run(...) 放在 if name == "__main__": 保护块中
  • 如果直接传入应用实例而不是导入字符串,则不能与多进程和热重载良好配合,因此更推荐使用 main:app 这种导入字符串形式

4.3 细粒度控制:Config 与 Server

如果需要更精细地控制服务生命周期,可使用 uvicorn.Config 与 uvicorn.Server:

import uvicorn

def main():
config = uvicorn.Config("main:app", host="127.0.0.1", port=5000, log_level="info")
server = uvicorn.Server(config)
server.run()

if __name__ == "__main__":
main()

如果当前已经处于异步环境中,可调用 await server.serve()。

第5章:配置方法总览

5.1 三种配置来源

根据官方文档,Uvicorn 配置主要有三种方式:

  • 命令行参数
  • uvicorn.run() 关键字参数
  • 环境变量,变量名前缀为 UVICORN_

例如:

set UVICORN_HOST=0.0.0.0

set UVICORN_PORT=8000

uvicorn main:app

优先级规则:

  • 命令行参数优先级最高
  • uvicorn.run() 显式参数也高于环境变量

5.2 --env-file 的作用边界

--env-file 常被误解。它主要用于给你的 ASGI 应用加载环境变量,而不是专门配置 Uvicorn 自身。

也就是说:

  • 应用自己的配置项可以通过 .env 进入进程环境
  • UVICORN_* 这类配置不应依赖 --env-file

第6章:常用配置项

6.1 应用定位

  • APP:应用入口,格式为 模块:对象
  • --factory:把入口当成工厂函数调用
  • --app-dir :把指定目录加入 Python 路径后再查找应用

示例:

uvicorn src.main:app --app-dir .

6.2 监听与绑定

--host:监听地址,默认 127.0.0.1

--port:监听端口,默认 8000

--uds:绑定 Unix Domain Socket

--fd:从已有文件描述符接管套接字

典型示例:

uvicorn main:app --host 0.0.0.0 --port 8000

如果希望局域网设备访问本机服务,通常需要把地址绑定到 0.0.0.0。

6.3 开发模式

  • --reload:开启自动重载
  • --reload-dir:指定监听目录,可多次传入
  • --reload-delay:重载检测间隔,默认 0.25
  • --reload-include:额外包含的文件模式
  • --reload-exclude:排除的文件模式

注意:

  • --reload 与 --workers 互斥,不能同时使用
  • 若未安装 watchfiles,Uvicorn 只能基于 *.py 文件修改时间做基础重载
  • 安装 watchfiles 后,--reload-include 和 --reload-exclude 才能生效

6.4 日志

  • --log-level:日志级别,可选 critical、error、warning、info、debug、trace
  • --access-log / --no-access-log:开启或关闭访问日志
  • --use-colors / --no-use-colors:彩色日志
  • --log-config:读取日志配置文件,支持 .ini、.json、.yaml

使用 YAML 日志配置时,需要项目里安装 PyYAML,或者直接安装 uvicorn[standard]。

6.5 实现层配置

  • --loop:事件循环实现,可选 auto、asyncio、uvloop
  • --http:HTTP 协议实现,可选 auto、h11、httptools
  • --ws:WebSocket 实现,可选 auto、none、websockets、websockets-sansio、wsproto
  • --lifespan:生命周期协议,可选 auto、on、off
  • --interface:接口类型,可选 auto、asgi3、asgi2、wsgi

平台与兼容性建议:

  • Windows 上不要强依赖 uvloop
  • 若追求最强兼容性,可显式指定 --loop asyncio --http h11
  • WSGI 模式会禁用 WebSocket,且官方已提示原生 WSGI 支持处于弃用路径,建议改用 a2wsgi

6.6 HTTP 与代理

  • --proxy-headers / --no-proxy-headers:是否读取代理头
  • --forwarded-allow-ips:指定可信代理来源
  • --root-path:设置 ASGI 的 root_path
  • --server-header / --no-server-header
  • --date-header / --no-date-header
  • --header Name:Value:添加默认响应头

如果服务部署在反向代理之后,务必只信任真正可控的代理地址;把 --forwarded-allow-ips 配成 * 之前,需要确认上游代理会清洗并重写转发头。

6.7 HTTPS

常用 TLS 参数:

  • --ssl-keyfile
  • --ssl-certfile
  • --ssl-keyfile-password
  • --ssl-version
  • --ssl-cert-reqs
  • --ssl-ca-certs
  • --ssl-ciphers

本地测试 HTTPS 示例:

uvicorn main:app --port 5000 --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem

6.8 资源限制与超时

--limit-concurrency:最大并发连接或任务数,超出可返回 503

--backlog:等待连接队列长度

--limit-max-requests:单进程最大请求数

--limit-max-requests-jitter:最大请求数的抖动值,避免同时重启

--timeout-keep-alive:Keep-Alive 超时

--timeout-graceful-shutdown:优雅关闭等待时间

--timeout-worker-healthcheck:worker 健康检查超时

这些选项更偏生产调优,在高并发或长时间运行场景下比较重要。

第7章:开发阶段常用命令

7.1 最常见的本地开发命令

uvicorn main:app --reload

7.2 指定多个热重载目录

uvicorn main:app --reload --reload-dir src --reload-dir app

7.3 指定日志级别

uvicorn main:app --reload --log-level debug

7.4 指定 WebSocket 或 HTTP 实现

uvicorn main:app --ws wsproto --http h11

7.5 从子目录加载应用

uvicorn main:app --app-dir src

第8章:生产部署建议

8.1 生产模式基本原则

官方部署文档给出的通用建议可以概括为:

  • 本地开发使用 uvicorn --reload
  • 生产环境使用进程管理方式运行
  • 自建部署通常建议放在 Nginx 之后
  • 更上层还可以放 CDN 或云负载均衡

8.2 直接使用 Uvicorn 多进程

Uvicorn 内置多进程管理能力:

uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

特点:

  • 适合较轻量的生产部署
  • Windows 也可工作,因为其多进程模型基于 spawn
  • 不能和 --reload 同时使用

8.3 与 Gunicorn 协作

官方文档仍然介绍了 Gunicorn 方案,但同时标注:

  • uvicorn.workers 模块已弃用
  • 后续推荐转向 uvicorn-worker 包

如果团队已有 Gunicorn 体系,可以继续关注官方迁移方向;如果是纯 Windows 环境,一般不会选择 Gunicorn 作为主方案。

8.4 放在 Nginx 后面

Nginx 常用于:

  • 静态资源处理
  • 缓冲慢请求
  • 统一入口与域名配置
  • WebSocket 代理
  • HTTPS 终止

Uvicorn 支持通过 --uds 绑定 Unix Domain Socket,再由 Nginx 反代过去。不过这类方式更常见于 Linux 服务器。

8.5 反向代理头配置

如果部署在 Nginx、云负载均衡、Ingress、CDN 之后,需要正确处理:

  • X-Forwarded-For
  • X-Forwarded-Proto

否则应用层拿到的客户端 IP、协议类型可能不正确。

8.6 HTTPS 建议

  • 生产环境通常由 Nginx、Ingress 或云负载均衡做 TLS 终止
  • 直接让 Uvicorn 挂证书更适合简单场景或本地测试
  • 如果自行配 TLS,证书建议使用可信 CA,如 Let's Encrypt

第9章:搭配 uv 的使用方式

这一章结合本仓库已有的 uv 使用方式,说明如何用 uv 来管理和运行 Uvicorn。

9.1 用 uv 安装 Uvicorn

安装为运行依赖

如果项目需要启动 Web 服务,建议把 Uvicorn 加入项目依赖:

uv add uvicorn

如果开发阶段需要热重载、.env、YAML 日志等增强能力,推荐直接安装标准扩展:

uv add "uvicorn[standard]"

执行后,uv 会:

  • 安装依赖到当前项目虚拟环境
  • 更新 pyproject.toml
  • 更新 uv.lock

安装为开发依赖

如果 Uvicorn 只用于本地调试,不作为生产运行依赖,也可以放到开发依赖中:

uv add --dev "uvicorn[standard]"

9.2 用 uv 运行 Uvicorn

uv 不要求你先手动激活虚拟环境,最常见方式是:

uv run uvicorn main:app --reload

这条命令的意义是:

  • 使用当前项目的虚拟环境
  • 查找其中安装的 uvicorn
  • 启动 main:app
  • 开启热重载

这也是最推荐的日常开发方式,因为不依赖终端是否已激活 .venv。

9.3 用 uv 运行包内模块

如果应用代码位于包结构内,例如:

quant_local/

web/

main.py

可以这样运行:

uv run uvicorn quant_local.web.main:app --reload

9.4 与本仓库工作流配合的建议

本仓库当前已经采用 pyproject.toml 和 uv 管理依赖,因此推荐保持一致:

  • 新增 Web 服务依赖时使用 uv add
  • 本地启动服务时使用 uv run uvicorn ...
  • 团队协作时提交 uv.lock,保证依赖版本一致
  • 若需要 .env 或更强热重载能力,统一使用 uvicorn[standard]

9.5 常见组合命令

本地开发

uv add --dev "uvicorn[standard]"
uv run uvicorn main:app --reload --host 127.0.0.1 --port 8000

局域网联调

uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

生产多进程

uv add uvicorn
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

9.6 Windows 环境补充说明

当前工作环境是 Windows,建议注意:

  • uvicorn[standard] 中的 uvloop 在 Windows 上不可用,这属于正常情况
  • 彩色日志支持通常由 colorama 提供
  • 如果在 WSL 中使用热重载,官方提到某些情况下需要设置 WATCHFILES_FORCE_POLLING

第10章:常见问题

10.1 为什么 --reload 不生效

常见原因:

  • 没有安装 watchfiles,只能做基础的 *.py 轮询检查
  • 监听目录不正确,需要加 --reload-dir
  • 在 WSL 下文件事件传递异常,需要额外设置轮询

10.2 为什么 --reload 和 --workers 不能一起用

因为一个偏开发期单进程重载,一个偏生产期多进程管理,官方明确将二者设为互斥。

10.3 为什么推荐使用 main:app 而不是直接传入对象

因为导入字符串方式更适合:

  • 多进程模式
  • 热重载模式
  • 统一启动入口

10.4 --env-file 为什么没把 UVICORN_PORT 生效

因为 --env-file 主要服务于应用自身环境变量,不是推荐用来驱动 UVICORN_* 配置的方式。

10.5 什么时候需要 --proxy-headers

当应用运行在反向代理之后,并且你希望应用正确识别真实客户端 IP 和协议时需要。但必须配合可信代理范围设置,不能无条件信任所有来源。

第11章:命令参考速查

11.1 基础命令


uvicorn main:app

uvicorn main:app --reload

uvicorn main:app --host 0.0.0.0 --port 8000

uvicorn --factory main:create_app

11.2 生产相关


uvicorn main:app --workers 4

uvicorn main:app --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem

uvicorn main:app --limit-concurrency 1000 --timeout-keep-alive 10

11.3 搭配 uv

uv add uvicorn
uv add "uvicorn[standard]"
uv add --dev "uvicorn[standard]"
uv run uvicorn main:app --reload
uv run uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

第12章:实践建议总结

12.1 开发环境建议

  • 优先安装 uvicorn[standard]
  • 启动命令优先使用 uv run uvicorn ...
  • 使用 --reload
  • 需要更细粒度监控时补充 --reload-dir

12.2 生产环境建议

  • 不使用 --reload
  • 用 --workers 或进程管理器提升稳定性
  • 放在反向代理之后
  • 明确配置可信代理范围
  • 在高负载场景下配置并发、超时、最大请求数等参数

12.3 团队协作建议

  • 统一采用 uv 管理依赖
  • 提交 uv.lock
  • 将服务启动命令写入 README 或脚本
  • 把开发命令与生产命令分开管理,避免误用

参考来源

第1章:uv 简介

1.1 什么是uv

uv是由Astral团队开发的高性能Python包管理器和虚拟环境管理器,使用Rust语言实现,旨在替代传统的pip、pipenv、poetry、virtualenv等工具。uv的核心定位是为Python开发者提供一个快速、可靠、功能全面的依赖管理解决方案。

uv的设计理念是"一次编写,到处运行",通过严格遵循PEP标准,确保与现有Python生态系统的完全兼容性,同时提供远超传统工具的性能表现。

1.2 主要特性

极致性能:采用Rust语言编写,依赖解析和包安装速度比传统工具快10-100倍,特别是在大型项目中优势更为明显

  • 功能集成:内置虚拟环境管理、依赖解析、包安装、版本锁定、脚本运行、包构建发布等全流程支持,无需额外安装其他工具
  • 兼容性:完全兼容PEP 508(依赖规范)、PEP 517/518(构建系统)、PEP 621(项目元数据)等标准,支持pyproject.toml、requirements.txt、setup.py等多种配置格式
  • 跨平台:原生支持Windows、macOS、Linux三大操作系统,提供一致的使用体验
  • 智能缓存:全局缓存下载的包和构建结果,避免重复下载和编译
  • 安全可靠:内置依赖漏洞扫描、哈希校验、签名验证等安全功能,保障依赖供应链安全

1.3 与传统工具对比

1.3.1 vs pip + virtualenv 组合

  • 优势:uv将虚拟环境管理和包管理集成在单个工具中,无需在多个工具间切换;依赖解析速度快,避免了pip常见的解析超时和版本冲突问题;内置锁文件机制,无需手动管理requirements.txt
  • 兼容性:完全支持pip的所有命令行参数和requirements.txt格式,可以无缝替换pip

1.3.2 vs Poetry

  • 优势:性能提升显著,特别是大型项目的依赖解析速度是Poetry的10-50倍;命令设计更简洁直观,学习成本更低;更严格的PEP标准兼容性,减少了自定义行为带来的兼容性问题
  • 兼容性:支持直接导入Poetry的pyproject.toml配置和poetry.lock文件,迁移成本低

1.3.3 vs Pipenv

  • 优势:性能优势巨大,解决了Pipenv长期存在的解析速度慢和稳定性问题;功能更全面,包含了Python版本管理、工作空间等高级功能;维护活跃,更新迭代速度快
  • 兼容性:支持导入Pipfile和Pipfile.lock,平滑迁移

1.3.4 vs Conda

  • 优势:更轻量级,启动速度快;专注于Python生态,与PyPI兼容性更好;磁盘占用更小,缓存机制更高效
  • 适用场景:uv更适合纯Python项目,Conda更适合数据科学场景中需要管理非Python依赖(如C/C++库)的情况

1.4 适用场景

  • 个人开发环境管理:快速创建和管理多个项目的虚拟环境,避免依赖冲突
  • 项目依赖管理:精确管理项目依赖版本,确保开发、测试、生产环境的一致性
  • CI/CD流水线:极快的依赖安装速度可以显著缩短构建时间,提高CI/CD效率
  • 多项目并行开发:工作空间功能支持在单个仓库中管理多个相关项目,共享依赖
  • 团队协作环境一致性:通过uv.lock文件确保团队所有成员使用完全相同的依赖版本
  • 开源库开发:内置的构建和发布功能,简化Python库的开发和发布流程

第2章:安装指南

2.1 系统要求

  • 支持的操作系统:

Windows 10 及以上版本

  • macOS 10.15 (Catalina) 及以上版本
  • Linux(支持glibc 2.17+和musl libc的主流发行版)
  • Python版本要求:Python 3.7 及以上版本(uv本身不依赖Python安装,但管理的项目需要Python环境)
  • 硬件要求:最低1GB内存,推荐2GB以上内存(大型项目依赖解析需要更多内存)

2.2 安装方法

2.2.1 官方脚本安装(推荐)

官方提供的安装脚本会自动检测系统环境,下载对应的预编译二进制文件并配置环境变量。

Linux/macOS 安装命令:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell 安装命令:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Windows CMD 安装命令:

curl -LsSf https://astral.sh/uv/install.ps1 -o install.ps1 && powershell -ExecutionPolicy ByPass -File install.ps1 && del install.ps1

2.2.2 包管理器安装

使用pip安装

如果系统中已经有Python环境,可以直接使用pip安装uv:

pip install uv

注意:使用pip安装的uv不会包含自更新功能,升级时需要重新使用pip命令。

使用Homebrew安装(macOS)
brew install uv

使用Scoop安装(Windows)

scoop install uv

使用Chocolatey安装(Windows)

choco install uv

使用apt安装(Debian/Ubuntu)

curl -fsSL https://packages.astral.sh/linux/astral.asc | sudo gpg --dearmor -o /usr/share/keyrings/astral-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/astral-archive-keyring.gpg] https://packages.astral.sh/linux/debian/ stable main" | sudo tee /etc/apt/sources.list.d/astral.list
sudo apt update && sudo apt install uv

使用yum/dnf安装(RHEL/CentOS/Fedora)

For RHEL/CentOS

sudo dnf config-manager --add-repo https://packages.astral.sh/linux/rhel/astral.repo
sudo dnf install uv

For Fedora

sudo dnf config-manager --add-repo https://packages.astral.sh/linux/fedora/astral.repo
sudo dnf install uv

2.2.3 预编译二进制下载

如果无法使用上述安装方法,可以手动下载预编译二进制文件:

  • 访问官方发布页面:https://github.com/astral-sh/uv/releases
  • 下载对应操作系统和架构的最新版本压缩包
  • 解压后将uv可执行文件放到系统PATH包含的目录中(如/usr/local/bin或%USERPROFILE%\AppData\Local\Programs\uv\bin)
  • 手动将uv的安装目录添加到系统环境变量PATH中

2.3 安装验证

安装完成后,打开新的终端窗口,执行以下命令验证安装是否成功:

uv --version

如果安装成功,会输出类似如下的版本信息:

uv 0.4.0 (a1b2c3d 2024-01-15)

进行基础功能测试:

uv --help

该命令会显示uv的帮助信息,列出所有可用命令。

2.4 版本升级

升级到最新正式版

如果是通过官方脚本安装的uv,可以使用自更新功能:

uv self update

升级到预发布版

如果想体验最新功能,可以升级到预发布版本:

uv self update --prerelease

指定版本升级

可以升级到指定的版本:

uv self update --version 0.4.0

注意:如果是通过包管理器(如pip、brew、scoop等)安装的uv,需要使用对应包管理器的升级命令。

2.5 卸载方法

官方卸载脚本

Linux/macOS 卸载命令:

curl -LsSf https://astral.sh/uv/uninstall.sh | sh

Windows PowerShell 卸载命令:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/uninstall.ps1 | iex"

手动卸载步骤

删除uv可执行文件:

Linux/macOS:rm ~/.cargo/bin/uv 或 rm /usr/local/bin/uv

Windows:删除 %USERPROFILE%.cargo\bin\uv.exe或安装时指定的目录

删除uv的配置和缓存目录:

Linux/macOS:rm -rf ~/.cache/uv ~/.config/uv

Windows:rmdir /s /q %LOCALAPPDATA%\uv\cache %APPDATA%\uv

从系统环境变量PATH中移除uv的安装目录

第3章:快速上手

3.1 基本概念

3.1.1 虚拟环境

虚拟环境是Python项目的隔离运行环境,每个项目可以拥有独立的依赖包版本,不会与其他项目或系统Python环境冲突。uv会自动管理虚拟环境的创建、激活和销毁。

3.1.2 依赖锁文件(uv.lock)

uv.lock是uv生成的依赖锁定文件,记录了所有依赖包的精确版本、下载地址和哈希校验值。确保在任何环境下安装的依赖版本完全一致,避免了"在我机器上能运行"的问题。

3.1.3 pyproject.toml 配置文件

pyproject.toml是PEP 621定义的Python项目标准配置文件,用于存储项目元数据、依赖声明、构建配置等信息。uv使用pyproject.toml作为默认的配置文件格式。

3.1.4 开发依赖 vs 生产依赖

  • 生产依赖:项目运行时必须的依赖包,如web框架、数据库驱动等
  • 开发依赖:仅在开发过程中需要的依赖包,如测试框架、代码检查工具、文档生成工具等

3.2 第一个uv项目

3.2.1 项目初始化

步骤1:新建项目目录

mkdir my-uv-project
cd my-uv-project

步骤2:初始化项目

uv init

执行该命令后,uv会自动完成以下操作:

  • 创建虚拟环境(默认在项目目录下的.venv文件夹)
  • 生成pyproject.toml配置文件
  • 生成README.md项目说明文件
  • 生成.gitignore文件(如果不存在)
  • 创建项目主模块目录

自动生成的文件结构说明:

my-uv-project/

├── .venv/ # 虚拟环境目录

├── pyproject.toml # 项目配置文件

├── uv.lock # 依赖锁文件

├── README.md # 项目说明文档

├── .gitignore # Git忽略文件

└── my_uv_project/ # 项目主模块目录

└── __init__.py # 模块初始化文件

pyproject.toml初始内容示例:

[project]

name = "my-uv-project"
version = "0.1.0"
description = ""
authors = [

{ name = "Your Name", email = "your.email@example.com" },

]

requires-python = ">=3.11"

dependencies = []

[tool.uv]

dev-dependencies = []

3.2.2 安装第一个包

安装生产依赖:

uv add requests

执行该命令后,uv会:

  • 解析requests的最新版本及其依赖
  • 安装requests到虚拟环境
  • 更新pyproject.toml中的dependencies列表
  • 更新uv.lock文件,记录所有依赖的精确版本

观察文件变化:

  • pyproject.toml中会添加:dependencies = ["requests>=2.31.0"]
  • uv.lock文件会记录requests及其所有依赖的精确版本、哈希值等信息

安装开发依赖:

uv add --dev pytest

pytest会被添加到dev-dependencies列表中,不会在生产环境中安装。

3.2.3 运行项目代码

创建测试脚本:

在项目根目录创建 test_requests.py文件:

import requests

def main():
response = requests.get("https://api.github.com")
print(f"GitHub API Status: {response.status_code}")
print(f"Rate Limit: {response.headers['X-RateLimit-Limit']}")

if __name__ == "__main__":

main()

使用uv运行脚本:

uv run test_requests.py

uv会自动激活当前项目的虚拟环境并运行脚本,无需手动激活环境。

激活虚拟环境的两种方式:

  • 手动激活(长期使用):
  • Linux/macOS:source .venv/bin/activate
  • Windows PowerShell:.venv\Scripts\Activate.ps1
  • Windows CMD:.venv\Scripts\activate.bat

激活后,终端提示符会显示虚拟环境名称,此时执行的所有Python命令都会使用虚拟环境中的版本。

  • 临时激活(单次命令):
    使用 uv run 前缀,如:
uv run python --version
uv run pip list

这种方式不需要手动激活和退出环境,适合执行单个命令。

退出虚拟环境:

如果手动激活了虚拟环境,执行以下命令退出:

deactivate

3.3 现有项目迁移

3.3.1 从requirements.txt迁移

如果项目使用requirements.txt管理依赖,可以直接导入:

uv pip install -r requirements.txt

或者初始化项目时自动导入:

uv init --from-requirements requirements.txt

3.3.2 从Poetry/Pipenv项目迁移

uv会自动识别Poetry的pyproject.toml和poetry.lock文件,以及Pipenv的Pipfile和Pipfile.lock文件。只需要在项目根目录执行:

uv sync

uv会自动导入现有配置并创建对应的虚拟环境和uv.lock文件。

3.3.3 现有虚拟环境导入

如果已经有现成的虚拟环境,可以指定uv使用该环境:

uv venv --python /path/to/existing/venv/bin/python

或者设置环境变量:

export VIRTUAL_ENV=/path/to/existing/venv

3.4 常用命令速览

环境相关命令

uv venv                    # 在当前目录创建 .venv
uv venv .venv-py312 -p 3.12  # 用指定 Python 创建虚拟环境
uv python list            # 列出可用/已安装的 Python 版本
uv python install 3.12    # 安装指定 Python 版本
uv python pin 3.12        # 为项目固定 Python 版本

依赖相关命令

uv add <package>                 # 添加依赖
uv add --dev <package>           # 添加开发依赖
uv remove <package>              # 删除依赖
uv lock                          # 生成或更新 uv.lock
uv lock --upgrade                # 升级全部可升级依赖并更新锁文件
uv lock --upgrade-package ruff   # 升级指定依赖
uv sync                          # 按锁文件同步环境
uv export -o requirements.txt    # 导出 requirements.txt
uv tree                          # 显示依赖树
uv pip list                      # 查看当前环境已安装包

运行相关命令

uv run <script>                  # 运行脚本
uv run python -m pytest          # 在项目环境中运行命令
uv tool run ruff check .         # 临时运行工具包命令
uv build                         # 构建源码包和 wheel

说明:不少旧教程中会出现 uv update、uv list、uv outdated、uv venv show 等写法。当前版本的 uv 更常通过 uv lock、uv sync、uv tree、uv pip list、uv python 等命令完成相同工作。

第4章:虚拟环境管理

4.1 虚拟环境基础

4.1.1 虚拟环境的作用和优势

虚拟环境的核心价值是隔离。每个项目拥有独立的解释器与依赖集合,可以避免:

  • 不同项目之间的版本冲突
  • 系统 Python 被污染
  • 团队成员环境不一致
uv 对虚拟环境的处理理念很直接:
  • 项目默认使用项目根目录下的 .venv
  • 大多数情况下不需要手动激活环境
  • 执行 uv run ...、uv add ...、uv sync 时,uv 会自动发现并使用项目环境

4.1.2 uv 的虚拟环境存储位置

  • 默认位置:项目目录下的 .venv
  • 可通过 uv venv 创建到其他位置
  • 在项目根目录运行时,可以通过环境变量 UV_PROJECT_ENVIRONMENT 修改默认环境目录名

4.1.3 虚拟环境的识别规则

根据当前 uv 的帮助信息,uv 会优先按如下顺序发现 Python 环境:

  • 当前已激活的虚拟环境
  • 当前目录及父目录中的 .venv
  • 系统 Python 或 uv 管理的 Python

这意味着在常规项目内,执行 uv run python 往往就会自动落到项目自己的 .venv。

4.2 创建虚拟环境

4.2.1 项目内虚拟环境

默认创建方式:

uv venv

该命令会在当前目录创建 .venv。

指定 Python 版本创建:

uv venv -p 3.12
uv venv -p cpython@3.12

如果本机没有对应版本,uv 可以根据配置自动下载。

创建到自定义位置:

uv venv .venv-py312
uv venv .cache/dev-env -p 3.12

带种子包创建:

uv venv --seed

这会把 pip、setuptools、wheel 等种子包放入环境,便于与传统工作流兼容。

4.2.2 全局或命名虚拟环境

当前版本 uv 的 venv 子命令是“创建一个虚拟环境到指定路径”,并不是维护一套独立的“命名环境注册表”。因此:

  • 可以创建任意路径的环境,例如 uv venv D:\envs\myenv
  • 但没有单独的 uv venv list 或 uv venv remove 子命令去集中管理所有环境

示例:

uv venv D:\envs\quant-dev -p 3.12

如果你希望长期维护多个命名环境,通常做法是:

  • 自己约定一个目录,例如 D:\envs\
  • 每个环境一个子目录
  • 用 uv run --project <项目目录> 或激活脚本切换使用

4.3 虚拟环境操作

4.3.1 激活虚拟环境

Linux/macOS:

source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

Windows CMD:

.venv\Scripts\activate.bat

4.3.2 临时激活

uv 更推荐的方式通常不是手动激活,而是直接运行:

uv run python --version
uv run pytest
uv run quant --help

这类命令会自动使用项目环境,更适合脚本化、CI 和团队协作。

4.3.3 查看虚拟环境信息

当前版本没有单独的 uv venv show。常用替代方式包括:

uv run python --version
uv run python -c "import sys; print(sys.executable)"

在 Windows 下也可以:

uv run python -c "import sys, site; print(sys.prefix); print(site.getsitepackages())"

4.3.4 退出虚拟环境

若使用了手动激活,可执行:

deactivate

4.4 虚拟环境管理

4.4.1 列出环境

当前版本 uv 没有集中列出所有虚拟环境的命令。可采用以下做法:

  • 统一约定环境目录并自行查看
  • 使用 uv python list 查看可用解释器
  • 用项目根目录的 .venv 作为标准约定,减少“列出环境”的需求

4.4.2 删除虚拟环境

当前版本 uv 没有 uv venv remove,删除方式就是直接删除环境目录。

Windows PowerShell 示例:

Remove-Item -Recurse -Force .venv

Linux/macOS 示例:

rm -rf .venv

4.4.3 重建环境

最常见的“修复环境”动作是删除并重建:

uv venv --clear
uv sync

或者:

rm -rf .venv
uv sync

其中 uv sync 会在需要时自动创建项目环境。

4.5 高级配置

4.5.1 配置默认虚拟环境位置

可以通过以下方式间接控制环境位置:

  • 在项目根目录使用标准 .venv
  • 通过 UV_PROJECT_ENVIRONMENT 变更默认环境目录名
  • 通过 uv venv 显式创建到特定路径

4.5.2 Python 版本管理

uv 内置了 Python 版本管理能力:

uv python list
uv python install 3.12
uv python pin 3.12
uv python find 3.12

相比依赖 pyenv、asdf 或手工安装,这种方式更统一,也更适合和项目约束联动。

4.5.3 Shell 集成

uv 自身不强依赖“自动激活 shell”工作流;在团队协作里更建议:
  • 命令前统一加 uv run
  • 将启动命令写进 README、任务脚本或 CI
  • 降低对交互式 shell 状态的依赖

第5章:依赖包管理

5.1 依赖管理基础

5.1.1 依赖类型

  • 生产依赖:放在 project.dependencies,运行时必须存在
  • 开发依赖:通常通过 uv add --dev 加入开发组,仅开发阶段需要
  • 可选依赖:可按 extra 组织,按需安装
  • 依赖组:可通过 --group 管理测试、文档、lint 等分组

5.1.2 版本约束语法

常见写法包括:

  • 精确版本:package==1.0.0
  • 最低版本:package>=1.0.0
  • 范围版本:package>=1.0.0,<2.0.0
  • 同主版本:通过 uv add --bounds major package
  • 同次版本:通过 uv add --bounds minor package
  • 精确锁定:通过 uv add --bounds exact package

此外还支持:

  • Git 依赖
  • 本地路径依赖
  • 可编辑依赖
  • 直接 URL 依赖

5.2 添加依赖

5.2.1 添加生产依赖

uv add requests
uv add pandas numpy

5.2.2 添加开发依赖

uv add --dev pytest
uv add --dev ruff mypy

5.2.3 添加到指定依赖组

uv add --group docs mkdocs
uv add --group lint ruff

5.2.4 指定版本或版本策略

uv add "fastapi>=0.116,<1.0"
uv add --bounds exact ruff
uv add --bounds major httpx

5.2.5 安装预发布版本

对预发布版,通常直接写入版本约束即可,例如:

uv add "package>=2.0.0rc1"

5.2.6 从 Git、本地路径安装

uv add git+https://github.com/encode/httpx
uv add .\libs\my_package
uv add --editable .

说明:

  • 当前版本 uv 常会把 Git、本地路径等来源信息写入 [tool.uv.sources]
  • 如果使用 uv add --raw,则会尽量按你输入的原始 requirement 直接写入依赖声明

5.3 依赖查询

5.3.1 查看已安装依赖

uv pip list
uv pip freeze

5.3.2 查看单个包详情

uv pip show pandas

5.3.3 查看依赖树

uv tree

5.3.4 查询说明

当前版本 uv 没有独立的 uv list、uv show、uv outdated 顶层命令。常见替代关系如下:

  • uv list -> uv pip list
  • uv show -> uv pip show
  • uv outdated -> 更常见做法是 uv lock --upgrade-package 试升级,或重新解析后观察 lockfile 变化

5.4 更新依赖

5.4.1 更新所有依赖

uv lock --upgrade
uv sync

第一步更新锁文件,第二步把环境同步到新锁文件版本。

5.4.2 更新指定包

uv lock --upgrade-package pandas
uv sync

5.4.3 仅更新锁文件

uv lock
uv lock --upgrade

5.4.4 校验锁文件是否最新

uv lock --check

这在 CI 中非常有用,可以防止 pyproject.toml 与 uv.lock 不一致。

5.5 删除依赖

5.5.1 删除依赖包

uv remove requests

5.5.2 删除开发依赖

uv remove --group dev pytest

删除完成后,建议执行一次:

uv sync

5.6 依赖同步

5.6.1 根据锁文件同步环境

uv sync

默认会做“精确同步”,把环境调整到与锁文件一致。

5.6.2 仅同步生产依赖

uv sync --no-dev

5.6.3 仅同步某些依赖组

uv sync --group docs
uv sync --only-group dev

5.6.4 不移除额外包

uv sync --inexact

5.7 依赖导出

5.7.1 导出为 requirements.txt

uv export -o requirements.txt

5.7.2 导出为 pylock.toml

uv export --format pylock.toml -o pylock.toml

5.7.3 排除开发依赖或本地包

uv export --no-dev -o requirements.txt
uv export --no-emit-local -o requirements-third-party.txt

5.7.4 不输出哈希

uv export --no-hashes -o requirements.txt

第6章:项目配置

6.1 pyproject.toml 配置详解

6.1.1 [project] 区段

该区段是标准 PEP 621 项目元数据区,常见字段包括:

  • name
  • version
  • description
  • readme
  • requires-python
  • dependencies
  • optional-dependencies
  • scripts

结合本仓库当前配置,可以看到如下典型结构:

[project]

name = "quant-local"
version = "0.1.0"

requires-python = ">=3.13"

[project.scripts]

quant = "quant_local.cli:app"

6.1.2 [tool.uv] 区段

该区段用于 uv 相关扩展配置,常见用途包括:

  • 开发依赖组
  • 默认依赖组行为
  • 解析冲突声明
  • 其他 uv 特定项目设置

本仓库目前使用了:

[tool.uv]

dev-dependencies = [

"pytest>=8.0.0",

"pytest-cov>=4.0.0",

]

6.1.3 [tool.uv.sources] 区段

当你添加 Git、本地路径、直接 URL 等来源依赖时,uv 常会在这里记录来源信息。

这有两个好处:

  • 让 project.dependencies 保持更干净
  • 把来源与版本控制信息单独管理

如果你希望“按输入原样写入依赖”,可以考虑 uv add --raw。

6.2 索引源配置

6.2.1 国内镜像配置

本仓库已经使用了清华镜像:

[[tool.uv.index]]

url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

这种配置适合国内网络环境,能够显著减少下载失败和解析等待。

6.2.2 多源优先级

当前 uv 支持多索引,并通过 index-strategy 决定解析策略。默认倾向于“先命中第一个有该包的索引”,这样能降低依赖混淆风险。

6.2.3 私有源认证

对于私有源,通常可通过以下方式配合:

  • 环境变量
  • 凭证管理器
  • keyring 子进程支持

如果涉及公司内部源,优先使用受控凭证方式,不要把令牌直接写进仓库。

6.3 环境变量配置

常见环境变量示例:

  • UV_PROJECT_ENVIRONMENT:修改项目环境目录名
  • UV_PYTHON:指定 Python 解释器请求
  • UV_CACHE_DIR:指定缓存目录
  • UV_DEFAULT_INDEX:设置默认索引
  • UV_INDEX:附加索引
  • UV_LOCKED:要求锁文件保持不变
  • UV_FROZEN:只按现有锁文件执行

使用建议:

  • 项目通用配置尽量放进 pyproject.toml
  • 机器相关配置优先放环境变量
  • CI 里显式设置 UV_LOCKED=1 或 UV_FROZEN=1,便于保证结果稳定

6.4 全局配置

当前版本 uv 主要通过以下位置读取配置:

  • 项目内 pyproject.toml
  • 独立的 uv.toml
  • 环境变量

需要注意:当前版本并没有单独的 uv config 顶层子命令,因此很多旧文章里提到的 uv config ... 并不适用于现在的命令集。

第7章:高级功能

7.1 工作空间(Workspace)管理

uv 支持 workspace 概念,但当前版本不是通过 uv workspace 单独管理,而是通过项目结构和命令参数协同完成。

在 workspace 场景里,常见相关参数包括:

  • --package :操作指定成员包
  • --all-packages:作用到所有成员包
  • --workspace:在某些命令中把本地路径加入 workspace 成员

适合场景:

  • Monorepo
  • 多个内部 Python 包共存
  • 核心库与应用共仓开发

7.2 脚本运行

7.2.1 基础运行

uv run python script.py
uv run pytest
uv run quant sync-data

7.2.2 运行带内联依赖的脚本

当前 uv 支持 PEP 723 脚本元数据。对于单文件脚本,依赖可以写在脚本里,由 uv run script.py 临时创建环境并运行。

这种方式适合:

  • 一次性脚本
  • 数据处理小工具
  • 教学示例

7.2.3 工具命令运行

uv tool run ruff check .
uv tool run mypy quant_local

如果你希望长期安装某个工具,也可以使用:

uv tool install ruff
uv tool list
uv tool upgrade ruff

7.3 包发布

7.3.1 构建包

uv build

通常会产出:

  • sdist
  • wheel

7.3.2 发布到索引

uv publish

如果发布到私有源,需要提前准备认证信息。

7.4 Python 版本管理

这是 uv 相比传统 pip + venv 工作流非常实用的地方。

常用命令:

uv python list
uv python install 3.12
uv python find 3.12
uv python pin 3.12
uv python uninstall 3.12

适合场景:

  • 本机尚未安装对应 Python
  • 多项目需要不同 Python 版本
  • CI 或新机器初始化环境

7.5 缓存管理

uv 的速度优势很大一部分来自缓存机制。

常用命令:

uv cache dir
uv cache clean
uv cache prune

建议:

  • 日常不要频繁清空缓存
  • CI 可以结合缓存目录做持久化
  • 只有在缓存损坏或磁盘空间紧张时再清理

7.6 安全与可重复性

当前版本 uv 顶层命令中没有独立的 uv audit。但在安全实践上,仍建议关注:

  • 使用锁文件固定版本
  • 使用可信索引源
  • 使用默认安全的多源解析策略
  • 在 CI 中执行 uv lock --check
  • 对第三方依赖另行接入安全扫描工具

如果团队有供应链安全要求,可以把依赖审计交给专门工具,而 uv 负责版本锁定和安装一致性。

第8章:工作流最佳实践

8.1 个人开发工作流

推荐流程:

  • uv init 初始化项目
  • uv python pin 3.12 固定 Python 版本
  • uv add / uv add --dev 添加依赖
  • uv run ... 执行脚本、测试和工具
  • uv lock --check 检查锁文件一致性

个人开发建议:

  • 保持 .venv 作为项目默认环境目录
  • 尽量不要混用系统 pip install
  • 使用 uv run 代替“先激活再运行”

8.2 团队协作工作流

8.2.1 项目配置标准化

  • 统一使用 pyproject.toml
  • 提交 uv.lock
  • 统一 Python 版本要求
  • 将常用命令写入 README 或任务脚本

8.2.2 CI/CD 集成建议

在 CI 中常见做法:

uv sync --frozen --no-dev
uv run pytest

或在校验阶段:

uv lock --check
uv sync --frozen

8.3 不同场景最佳实践

8.3.1 数据科学项目

固定 Python 与关键数值库版本

使用镜像源减少大包下载失败

在 CI 或共享机器上利用缓存

8.3.2 Web 开发项目

这一部分结合 uvicorn 官方文档说明 uv 与 Web 服务启动的配合方式。

如果项目使用 ASGI 服务,推荐:

uv add "uvicorn[standard]"
uv run uvicorn main:app --reload

说明:

  • uvicorn[standard] 通常会带上 watchfiles、websockets、httptools 等开发期常用增强依赖
  • uv run uvicorn ... 不依赖你是否已手动激活 .venv
  • --reload 适合本地开发

生产场景常见做法:

uv add uvicorn
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

结合 uvicorn 官方文档,还需要注意:

  • --reload 与 --workers 互斥,不能一起用
  • 如果使用应用工厂,可执行 uv run uvicorn --factory main:create_app
  • 如果要在代码中启动,可以用 uvicorn.run("main:app", ...)

8.3.3 命令行工具开发

如果你的项目像本仓库一样已经有 [project.scripts]:

[project.scripts]

quant = "quant_local.cli:app"

那么开发阶段很适合:

uv run quant --help

8.3.4 库开发项目

使用 uv build 验证打包输出

把测试、lint、docs 放入不同依赖组

在发布前确保锁文件与元数据同步

8.4 性能优化技巧

使用本地镜像或公司代理源

利用 uv 的缓存,不要频繁清空

在 Docker / CI 中先安装第三方依赖,再安装本地项目

使用 uv sync --frozen 减少不必要解析

8.5 常见陷阱与规避

不要把系统 pip 和项目 uv 工作流混在一起

不要随手删除 uv.lock 后忘记重新提交

不要在生产环境使用 --reload

对多源解析,优先使用默认安全策略,避免依赖混淆

第9章:常见问题(FAQ)

9.1 安装问题

安装失败常见原因

网络访问 PyPI 慢或超时

公司代理或证书链问题

Python 版本不满足项目约束

解决建议

配置国内镜像源

必要时启用系统证书存储或公司代理证书

先执行 uv python list / uv python install 准备解释器

9.2 虚拟环境问题

虚拟环境无法激活

先确认环境是否存在:

uv run python --version

如果能运行,通常说明环境本身没有问题,只是 shell 激活脚本没有生效。

Python 版本不匹配

检查:

uv run python --version
uv python find 3.12

9.3 依赖安装问题

依赖解析失败

常见原因:

  • 版本约束彼此冲突
  • 某些包在当前 Python 版本无可用 wheel
  • 源中没有对应版本

排查建议:

  • 缩小版本约束范围
  • 切换 Python 版本再试
  • 使用 uv tree 观察依赖关系

二进制包安装问题

Windows 上部分科学计算包对 Python 版本和架构更敏感,优先选择官方支持好的 Python 版本组合。

9.4 性能问题

依赖解析慢怎么办

  • 配置镜像源
  • 复用缓存
  • 减少不必要的源切换

安装速度慢怎么办

  • 检查是否每次都在清缓存
  • 在 CI 中缓存 uv 缓存目录
  • 优先使用 wheel 丰富的版本组合

9.5 兼容性问题

与其他工具共存

可以共存,但建议一个项目只选择一套主工作流:

  • 要么用 uv
  • 要么继续用 Poetry / Pipenv

混用最容易导致锁文件、环境和依赖声明不一致。

旧项目迁移时最常见的问题

  • requirements.txt 能装,但缺少项目元数据
  • 原来依赖是手工 pip 安装,没有完整声明
  • Python 版本约束没有写进项目配置

9.6 其他常见问题

uv.lock 要不要提交到 Git

通常要提交。这样团队成员、CI 与生产环境可以保持一致依赖解析结果。

如何回滚依赖版本

  • 回退 pyproject.toml
  • 回退 uv.lock
  • 再执行 uv sync --frozen

如何清理未使用依赖

  • 从 pyproject.toml 移除对应依赖
  • 执行 uv remove
  • 再执行 uv sync

私有源配置问题

优先把凭据放在环境变量或凭证管理器里,不要提交到仓库。

附录A:命令参考大全

A.1 核心命令

  • uv init:初始化项目
  • uv add:添加依赖
  • uv remove:删除依赖
  • uv lock:生成或更新锁文件
  • uv sync:同步项目环境
  • uv run:在项目环境中运行命令或脚本

A.2 管理命令

  • uv self update:升级 uv 自身
  • uv python:管理 Python 版本
  • uv cache:管理缓存
  • uv tool:管理全局/临时工具

A.3 信息查询命令

  • uv tree:查看依赖树
  • uv pip list:查看当前环境已安装包
  • uv pip show :查看包详情
  • uv python list:查看可用 Python

A.4 发布相关命令

  • uv export:导出锁文件到其他格式
  • uv build:构建包
  • uv publish:发布包

A.5 工作空间相关

  • uv add --package :为指定成员包添加依赖
  • uv sync --package :同步指定成员包
  • uv sync --all-packages:同步整个 workspace

附录B:配置文件参考

B.1 pyproject.toml 完整配置示例

结合本仓库现状,可参考:

[project]

name = "quant-local"
version = "0.1.0"
description = "本地量化数据分析 MVP 系统"
readme = "README.md"

requires-python = ">=3.13"

[project.scripts]

quant = "quant_local.cli:app"

[[tool.uv.index]]

url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[tool.uv]

dev-dependencies = [

"pytest>=8.0.0",

"pytest-cov>=4.0.0",

]

B.2 常用环境变量

UV_PROJECT_ENVIRONMENT

UV_PYTHON

UV_CACHE_DIR

UV_DEFAULT_INDEX

UV_INDEX

UV_LOCKED

UV_FROZEN

B.3 全局配置选项

优先级通常为:

  • 命令行参数
  • 项目配置文件
  • uv.toml
  • 环境变量

具体行为以当前 uv 版本文档和帮助输出为准。

附录C:迁移指南

C.1 从 pip + virtualenv 迁移

推荐步骤:

  • 补齐 pyproject.toml
  • 用 uv add 或 uv pip install -r requirements.txt 导入依赖
  • 生成 uv.lock
  • 统一改用 uv run、uv sync

C.2 从 Poetry 迁移

  • 保留原有 pyproject.toml
  • 用 uv 在项目根目录重新解析并生成 uv.lock
  • 对照原依赖组与脚本定义做兼容性检查

C.3 从 Pipenv 迁移

  • 把 Pipfile 中的依赖迁入 pyproject.toml
  • 使用 uv add --dev 重建开发依赖组
  • 删除旧虚拟环境后重新 uv sync

C.4 从 Conda 迁移

  • 区分 Python 依赖和非 Python 依赖
  • 纯 Python 项目适合直接迁移到 uv
  • 依赖大量系统库的项目需要评估是否保留 Conda 管理底层运行时

附录D:术语表

  • 虚拟环境:隔离的 Python 运行环境
  • 锁文件:记录精确依赖解析结果的文件,本手册中指 uv.lock
  • 依赖组:开发、文档、测试等按用途划分的依赖集合
  • Workspace:单仓库多 Python 包协同开发结构
  • PEP 621:Python 项目元数据标准
  • PEP 723:脚本内联依赖元数据标准
  • ASGI:异步 Python Web 服务器接口标准,Uvicorn 属于此生态常用服务端