知行迭代 - 用户贡献 [zh-cn]

AI编程

2026-05-11T03:08:24Z

Eric：/* UI/UX 设计 */

AI编程是利用[[AI]]技术来自动生成、补全、优化代码，提高开发效率。

==工具==
===AI代码补全与代码助手===
*GitHub Copilot
Tabnine
*Codeium

===AI IDEs===
* Cursor
* Trae AI IDE

===AI 编码代理===
* [[Claude Code]]
* [[OpenCode]]，开源的AI编码代理工具。

== 编程大模型 ==
* [[Claude]]
* [[ChatGPT]]
* [[DeepSeek]]
* Qwen
* Gemini

== AI开发App ==
=== 想法验证与需求分析 ===
把模糊的想法变成可执行的文档。明确问题与目标：描述App解决什么痛点、目标用户、核心功能等。
工具：ChatGPT / DeepsSeek / Claude / Gemini
操作：向 AI 描述你的初步想法。例如：“我想做一个针对小学生的阅读进度记录 App，需要有勋章系统和家长端。请帮我梳理核心功能点和用户流程图。”
验证可行性：AI生成市场分析
产出：PRD（产品需求文档）和功能清单。

=== UI/UX 设计 ===

产出：UI 设计稿或前端交互原型。

==== 直接生成 ====
直接提示词，搭配skill，直接生成界面。
*ui-ux-pro-max-skill， https://www.uupm.cc， https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

==== 原型工具 ====
AI提示词给原型工具，交互式生成UI，再导出编程。
* google stitch
* pencil.dev
* figma

==== 原型图 ====
先生成图，再给AI还原，或者先给原型工具，再导出。
* 即梦
* GPT Image 2

=== 技术选型与架构设计 ===

===开发编码===

===测试===
用 AI 批量生成测试用例，自动执行和查错。

===构建与部署===

===上线监控与持续迭代===

Samba

2026-05-10T15:28:47Z

Eric：/* 服务端配置 */

Samba是一个开源软件套件，允许Linux和Unix系统与Windows系统共享文件和打印机。它通过SMB/CIFS协议实现互操作性。

==简介==
===时间轴===

==快速入门==
===安装===
Ubuntu/Debian:
<syntaxhighlight lang="bash" >
sudo apt-get update
sudo apt-get install samba
</syntaxhighlight>

===配置Samba===
Samba的配置文件通常位于/etc/samba/smb.conf。没有新建一个。
<syntaxhighlight lang="text" >
[global]
workgroup = WORKGROUP
server string = Samba Server
netbios name = linuxserver
security = user

[shared]
path = /home/username/shared
browsable = yes
writable = yes
guest ok = no
read only = no
</syntaxhighlight>
配置说明：
* [global]：定义全局设置。
** workgroup：工作组名称，通常与Windows系统的工作组一致。
** server string：服务器的描述文字。
** netbios name：服务器的NetBIOS名称。
** security = user：启用用户级安全认证。
* [shared]：定义一个共享目录。
** path：共享目录的路径。
** browsable：允许客户端浏览此共享。
** writable：允许写入权限。
** guest ok：是否允许匿名访问（此处为否）。
** read only：是否只读（此处为否）。

===创建共享目录===
创建配置文件中指定的共享目录，并设置适当的权限：
<syntaxhighlight lang="bash" >
sudo mkdir -p /home/username/shared
sudo chown -R nobody:nogroup /home/username/shared
sudo chmod -R 0700 /home/username/shared
</syntaxhighlight>

===添加Samba用户===
Samba使用独立的密码数据库。需要为系统用户创建Samba账，如username：
<syntaxhighlight lang="bash" >
# 如果还不是系统用户，需要先创建
# sudo adduser username

sudo smbpasswd -a username
</syntaxhighlight>

===启动和启用Samba服务===
<syntaxhighlight lang="bash" >
sudo systemctl start smbd
sudo systemctl enable smbd
</syntaxhighlight>

===访问共享===
在Windows系统中，可以通过以下方式访问Samba共享：
打开“文件资源管理器”，输入\\linuxserver\shared（用服务器的IP地址或NetBIOS名称替换linuxserver）。
或使用“映射网络驱动器”功能连接到共享。

==服务端配置 ==

=== 创建只能使用samba用户 ===
<syntaxhighlight lang="bash" >
# -m 创建用户主目录
# -s /sbin/nologin 用户无法通过 SSH、控制台等方式登录系统
# 有些路径, /usr/sbin/nologin
sudo useradd -m -s /sbin/nologin user1

# 设置 Samba 密码，独立于系统密码
sudo smbpasswd -a user1

# 配置 Samba 共享目录
sudo nano /etc/samba/smb.conf

# 添加下面内容，并保存
[user1]
comment = Data Share
path = /home/user1
browseable = yes
writable = yes
valid users = user1
create mask = 0755
directory mask = 0755

# 重启 Samba 服务
sudo systemctl restart smbd
</syntaxhighlight>

==客户端挂载 ==
===linux挂载===
图形界面挂载Samba共享：
*打开文件管理器，点击侧边栏‘网络’，输入服务器地，如<code>smb://192.168.1.100/YourShare</code>，点击连接。

使用[[mount]]命令行挂载：
<syntaxhighlight lang="bash" >
# 安装 cifs-utils 来支持挂载命令
sudo apt install cifs-utils -y

# 创建挂载点
mkdir ~/mysambashare

# 执行挂载，输入密码 (Samba 密码)
sudo mount -t cifs //192.168.1.100/YourShare ~/mysambashare -o username=your_username

# 使用凭据文件，免每次手动输密码。
# 1. 创建文件（替换 username 和 password）
echo -e "username=your_username\npassword=your_password" > ~/.smbcredentials
# 2. 设置权限（重要：防止泄露）
chmod 600 ~/.smbcredentials
# 3. 挂载时引用
sudo mount -t cifs //192.168.1.100/YourShare ~/mysambashare -o credentials=~/.smbcredentials

# 开机自动挂载
# 编辑 fstab
sudo nano /etc/fstab
# 在fstab文件，在末尾添加一行，
# 为避免报错导致无法开机，强烈建议使用 x-systemd.automount 或 nofail 选项。
//192.168.1.100/YourShare /home/your_username/mysambashare cifs credentials=/home/your_username/.smbcredentials,uid=你的本地uid,gid=你的本地gid,iocharset=utf8,nofail,x-systemd.automount 0 0

# 测试挂载
sudo mount -a
</syntaxhighlight>

===windows挂载===
==资源==
===官网===
* Samba官网：https://www.samba.org/
* Samba Wiki：https://wiki.samba.org/

===网站===
*Ubuntu教程：安装和配置Samba https://ubuntu.com/tutorials/install-and-configure-samba

AI编程

2026-05-09T02:52:08Z

Eric：

AI编程是利用[[AI]]技术来自动生成、补全、优化代码，提高开发效率。

==工具==
===AI代码补全与代码助手===
*GitHub Copilot
Tabnine
*Codeium

===AI IDEs===
* Cursor
* Trae AI IDE

===AI 编码代理===
* [[Claude Code]]
* [[OpenCode]]，开源的AI编码代理工具。

== 编程大模型 ==
* [[Claude]]
* [[ChatGPT]]
* [[DeepSeek]]
* Qwen
* Gemini

== AI开发App ==
=== 想法验证与需求分析 ===
把模糊的想法变成可执行的文档。明确问题与目标：描述App解决什么痛点、目标用户、核心功能等。
工具：ChatGPT / DeepsSeek / Claude / Gemini
操作：向 AI 描述你的初步想法。例如：“我想做一个针对小学生的阅读进度记录 App，需要有勋章系统和家长端。请帮我梳理核心功能点和用户流程图。”
验证可行性：AI生成市场分析
产出：PRD（产品需求文档）和功能清单。

=== UI/UX 设计 ===

产出：UI 设计稿或前端交互原型。

=== 技术选型与架构设计 ===

===开发编码===

===测试===
用 AI 批量生成测试用例，自动执行和查错。

===构建与部署===

===上线监控与持续迭代===

Flutter

2026-05-08T06:08:51Z

Eric：

Flutter 是一个[[Google]]开源的跨平台软件开发工具，支持开发[[Android]]、 [[iOS]] 、 [[web]]、 [[Windows]]、 [[macOS]] 和 [[Linux]] 等应用。

==简介==
===时间轴===
===安装===
==== Window上安装 ====
* 1.下载Flutter SDK最新的Stable版本： https://docs.flutter.dev/release/archive?tab=windows
* 2.解压缩到某个位置，如D:\flutter。
* 3.添加到flutter\bin到环境变量path中。搜索框输入env进入设置。
* 4.国内配置镜像源
* 5运行<code>flutter doctor</code> 检查环境。

{{了解更多
|[https://docs.flutter.dev/get-started/install/windows Flutter 文档：Windows 安装 Flutter ]
}}

==== 国内配置镜像源 ====

Window配置： 
搜索框输入env，点击编辑系统环境变量，将PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 和其值添加到用户变量中。

Linux配置：
<syntaxhighlight lang="bash">
# 临时配置
export FLUTTER_STORAGE_BASE_URL="https://mirrors.tuna.tsinghua.edu.cn/flutter"
export PUB_HOSTED_URL="https://mirrors.tuna.tsinghua.edu.cn/dart-pub"

# 长期配置
echo 'export FLUTTER_STORAGE_BASE_URL="https://mirrors.tuna.tsinghua.edu.cn/flutter"' >> ~/.bashrc
echo 'export PUB_HOSTED_URL="https://mirrors.tuna.tsinghua.edu.cn/dart-pub"' >> ~/.bashrc
</syntaxhighlight >

====安装后续====
安装完成后，可以查看版本：
<syntaxhighlight lang="bash">
# 查看dart语言版本
dart --version

# 查看flutter版本，卡住通常是因为网络问题
flutter --version

# 禁用 Google Analytics（可选）
flutter --disable-analytics

# 运行 Flutter Doctor 检查环境
# Android SDK 是否安装
# Chrome/Edge 是否可用
# CMake、ninja等依赖项目
flutter doctor

</syntaxhighlight >

Android SDK，地址：https://developer.android.com/tools?hl=zh-cn。Android SDK包含了多个包，可以使用 sdkmanager 命令行工具来安装和更新每个软件包。sdkmanager在cmdline-tools包括中。
* 安装 cmdline-tools，参考：https://developer.android.com/tools/sdkmanager?hl=zh-cn。在 https://developer.android.com/studio?hl=zh-cn#command-line-tools-only 页面下方找到对应平台，如https://dl.google.com/android/repository/commandlinetools-linux-14742923_latest.zip。

*安装最新版SDK工具，如API 级别 36 的 SDK 工具： sdkmanager "platform-tools" "platforms;android-36"

{{了解更多
|[https://flutter.cn/community/china Flutter 文档中文版：在中国网络环境下使用 Flutter ]
|[https://mirrors.tuna.tsinghua.edu.cn/help/flutter/ 清华大学开源软件镜像站：Flutter 镜像安装帮助 ]
}}

==快速入门==
===新建flutter项目===
方法一：在 VS Code 中创建，Ctrl + Shift + P ，在命令面板中输入 flutter，找到并选择 Flutter: New Project，在弹出的选项中选择 Application（创建一个标准 Flutter 应用）

方法二：在终端/命令行中创建。
<syntaxhighlight lang="bash">
# 以 projects 文件夹为例
cd ~/projects

# 当前目录下创建一个名为 my_app 的文件夹
# 并生成完整的项目代码
flutter create my_app

# 创建最小化项目（空的 main.dart）
flutter create --empty my_app
# 指定支持的平台
flutter create --platforms=android,ios,web my_app
</syntaxhighlight >

https://docs.flutter.dev/reference/create-new-app

===项目结构速览===
<syntaxhighlight lang="text">
my_app/
├── android/ # Android 原生代码
├── ios/ # iOS 原生代码
├── lib/ # 📁 你的 Dart 代码（主要工作区域）
│ └── main.dart # 入口文件
├── test/ # 单元测试代码
├── pubspec.yaml # 项目配置文件（依赖、资源等）
└── ... # 其他配置文件
</syntaxhighlight >

===运行项目===
项目创建成功后，在项目目录下执行，然后选择你要运行的设备（模拟器或真机）：
flutter run
或者在scode中点击my_app/lib/main.dart文件，然后点击右上角运行按钮。

==资源==
===官网===
* Flutter 官网： https://flutter.dev
* Flutter 源代码：https://github.com/flutter/flutter
* Flutter 示例：https://flutter.github.io/samples
* Material 3 ：https://m3.material.io

===网站===
* Flutter 文档中文版：https://flutter.cn
* 《Flutter实战·第二版》： https://book.flutterchina.club
* liujunmin.com 博客分类：https://liujunmin.com/categories/

Flutter

2026-05-08T03:52:50Z

Eric：

Flutter

2026-05-08T02:20:34Z

Eric：/* 安装后续 */

2026-04-29T13:56:22Z

Eric：

KVM虚拟机

2026-04-29T12:10:27Z

Eric：

Ubuntu

2026-04-29T06:53:33Z

Eric：/* 常见问题 */

Ubuntu是一个[[Linux]]的发行版，由Canonical公司发布并提供商业支持。Ubuntu项目公开承诺开源软件开发的原则；鼓励人们使用自由软件，研究它的运作原理，改进和分发。Ubuntu是著名的[[Linux]]发行版之一，基于[[Debian]]发行版和GNOME桌面环境。

==简介==
===时间轴===
*2004年10月20日，马克·舍特尔沃斯创立并发布Ubuntu第一个版本Ubuntu 4.10，它以Debian为开发蓝本。
*2005年7月8日，马克·舍特尔沃斯与Canonical有限公司宣布成立Ubuntu基金会，并提供1千万美元作为启始营运资金。但直至2006年，此基金会仍未投入运作。马克·舍特尔沃斯形容此基金会是在Canonical有限公司出现财务危机时的紧急营运资金。

===版本===

===安装===
====制作启动U盘====
Ubuntu官网下载ISO镜像。

linux中制作启动U盘：
方法一：使用dd命令，一定要注意看清楚哪个盘，不然可能格式化错盘。
<syntaxhighlight lang="bash">
# 插入u盘，查看所有块设备：
lsblk

# 使用dd命令写入ISO到U盘，如u盘为sdx：
sudo dd if=/path/to/ubuntu.iso of=/dev/sdx bs=4M status=progress

# 安全移除U盘
sudo eject /dev/sdx
</syntaxhighlight>

windows中制作启动U盘：
方法一，Ubuntu官方教程使用[[Rufus]]软件制作启动U盘，下面使用[[UltraISO]]软件制作启动U盘，只是写启动盘可以用试用版。
*打开UltraISO，选择下载好的Ubuntu系统
*点击菜单栏‘启动’》‘写入硬盘映像’
*在对话框的‘硬盘驱动器’处选择要刻录的U盘
*然后点击‘写入’，注意U盘会被格式化所有资料都没有
*启动U盘制作完成，可以用它在任何电脑安装Ubuntu

方法二，也可以使用<code>diskpart</code>和<code>xcopy</code>命令行制作ubuntu的启动U盘，在如下：
* 搜索框输入<code>cmd</code>，打开命令提示符。
* 在cmd中输入<code>diskpart</code> ，打开磁盘管理。
* <code>list disk</code>，查看所有磁盘信息。
* <code>select disk 2</code>，选择U盘，示例U盘为disk 2。
* <code>clean</code>，清除U盘。
* <code>create partition primary</code>，创建分区。
* <code>select partition 1</code>，选择分区1。
* <code>active</code>，将当前分区标记为活动。
* <code>format fs=ntfs quick</code>，格式化分区为ntfs格式。
* <code>assign</code>，分配盘符。
* <code>exit</code>，退出。
* 选择下载好的iso文件，右键点击装载。查看装载后的盘符，如<code>G：</code>
* <code>xcopy G:\*.* /e /h /f H:\</code>，复制所有文件到U盘。其中<code>H:</code>为U盘的盘符。<code>/e</code>复制所有子目录，即使它们是空的。<code>/h</code>复制具有隐藏文件和系统文件属性的文件。 <code>/f</code>复制时显示源文件名和目标文件名。

{{了解更多
|[https://ubuntu.com/tutorials/tutorial-create-a-usb-stick-on-windows#1-overview Ubuntu 教程：Windows上制作启动U盘]
|[https://learn.microsoft.com/zh-cn/windows-server/administration/windows-commands/xcopy Windows Server文档：xcopy]
}}

====安装到电脑====

====安装到U盘====

====分区方案====
{{Linux分区方案}}
==技巧==
*创建某个目录在桌面快捷方式
点击某个目录，按住Ctrl + Shift，拖动到桌面目录(文件打开)里，注意不能直接拖动到桌面。

==软件==
===软件安装===
====apt====

====deb====

====AppImage====
是Linux上的一种应用打包格式，将程序所有文件打包成一个AppImage，可以在不同Linux发行版上运行。直接运行，不需要安装运行库。

运行AppImage格式程序
<syntaxhighlight lang="bash" >
# 进入AppImage 文件所在目录，为文件添加可执行权限
cd /path/to/directory
chmod +x example.AppImage

# 直接运行文件
./example.AppImage
</syntaxhighlight>

===快捷方式===
应用程序和桌面创建快捷方式。.desktop 文件是 Linux 桌面环境中用于定义应用程序启动器、菜单项或快捷方式的配置文件。常用文件内容如下：
*Name：应用程序的显示名称（必填）。
*Exec：启动应用程序的命令（必填），路径使用绝对路径。
*Type：定义文件类型，常见值：Application：应用程序，Link：快捷方式，Directory：目录
*Icon：Ubuntu支持的图标格式包括 PNG、SVG、XPM。注意路径最后面不要有空格，否则图标不会显示。图标可以在提取文件里找<code>./example.AppImage --appimage-extract</code>
<syntaxhighlight lang="bash" >
# 创建 .desktop 文件
vim ~/.local/share/applications/example.desktop

# 编辑 .desktop 文件内容
[Desktop Entry]
Name=Example App
Exec=/path/to/example.AppImage
Type=Application
Terminal=false
Icon=/path/to/icon.png
Comment=Example App Shortcut
Categories=Utility;

# 保存并赋予权限
chmod +x ~/.local/share/applications/example.desktop

# 复制到桌面
# 桌面上点击图标，右键，点击允许运行
cp ~/.local/share/applications/example.desktop ~/Desktop/
</syntaxhighlight>

====Edge多个用户启动====
Edge地址栏输入并访问 edge://version/，找到 "个人资料路径" 这一栏。路径末尾的 Default 就是你的默认用户的目录名。第二个用户通常名为 Profile 1、Profile 2，或是你自定义的名称。示例，创建不同的 .desktop 文件，启动时指定不同Edge用户：
nano ~/.local/share/applications/edge-profile1.desktop
输入如下内容，ctrl+o保存，ctrl+x退出：
<syntaxhighlight lang="bash" >
[Desktop Entry]
Type=Application
Name=Edge 用户1
Exec=/usr/bin/microsoft-edge --profile-directory="Profile 1"
# 或者Icon=/path/to/microsoft-edge.Profile1.png
Icon=microsoft-edge
Terminal=false
Comment=使用个人资料1打开Microsoft Edge
# Categories=Network;
# StartupWMClass=edge-profile1 # 用于区分窗口

</syntaxhighlight>
点击系统菜单，显示所有应用，找到刚才命名的名字“Edge - 用户1”，右键点击它的图标，选择“添加到收藏夹”或“添加到Dock”。

===常用软件===
{| class="wikitable" style="width: 100%;
! 名称
! 描述
! 网址
|-
| [[KVM]]
|
|
|-
| [[VLC]]
| VLC是一款开源的、免费的多平台视频播放器，支持MPEG-2, MPEG-4, H.264, MKV, WebM, WMV, MP3等格式。安装命令：sudo apt install vlc
| [https://www.videolan.org/vlc/ 官网]
|-
| [[VMware Workstation]]
|
| [https://www.vmware.com/products/workstation-pro.html 官网] [https://www.vmware.com/products/workstation-pro/workstation-pro-evaluation.html 下载]
|-
| WPS
| 金山办公套装软件,支持多人在线协作编辑Word、Excel和PPT文档。 安装： 常见问题： *缺少系统字体：Symbol、Wingdings 1、Wingdings 2、Wingdings 3、Webdings、MT Extra， WPS无法正确地显示某些符号公式。因为这些字体是 Microsoft Windows 系统中的专有字体，而 Ubuntu 默认并未包含它们。 解决方法： 1.下载字体，从windows中复制字体C:\Windows\Fonts，或者web上搜索字体下载，或者从https://github.com/dv-anomaly/ttf-wps-fonts。 2.安在到系统中，
<syntaxhighlight lang="bash" >
sudo mkdir -p /usr/share/fonts/wps-office
cd ~/Downloads/ttf-wps-fonts-master # 进入下载好的目录
sudo cp mtextra.ttf symbol.ttf wingding.ttf WINGDNG3.ttf WEBDINGS.TTF WINGDNG2.ttf /usr/share/fonts/wps-office/
sudo fc-cache -fv
</syntaxhighlight>
|[https://platform.wps.cn/ 下载]
|-
| [[IBus]]
| Ubuntu 24.04及其他各大[[Linux]]发行版的默认的多语输入平台。支持用户词典、用户lua脚本。
| [https://github.com/ibus/ibus/wiki 官网]
|-
| [[搜狗输入法]]
| 有自定义短语功能，支持多行空格等。Windows上有广告弹窗，安装其他软件。 安装： 1.安装fcitx。<code>sudo apt-get install fcitx</code> 2.添加中文语言支持 3.下载安装搜狗输入法。<code>sudo dpkg -i sogoupinyin_版本号_amd64.deb</code> 。如果安装过程提示缺少依赖<code>sudo apt -f install</code> 设置为默认输入法，点击桌面右上角键盘图标->设置(Configure)->Input Method将sougoupinyin移动到最上边。
| [https://pinyin.sogou.com/linux/ 官网] [https://pinyin.sogou.com/linux/help.php 安装指南]
|-
| 网易音乐
| 安装： 1.点击下载客户端，其他操作系统客户端，Linux版 2.双击下载的deb文件安装
| [https://music.163.com/ 官网] [https://music.163.com/#/download 下载]
|-
| qq音乐
|
| [https://y.qq.com/download/download.html 下载]
|-
| [[Conky]]
| 桌面环境的系统监控工具。免费开源，高度可定制。 安装：<code>sudo apt-get install conky</code>
| [https://github.com/brndnmtthws/conky 官网]
|-
| btop
|
|
|}

==用户管理==

==网络设置==
===防火墙设置===

==安装驱动==
===显卡驱动===
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| Ubuntu软件库安装
| 推荐方法，简单快捷可更新。 安装步骤： 1.更新软件库 <code>sudo apt-get update</code> 2.查找相关驱动 <code>sudo ubuntu-drivers devices</code> ，后面带recommend是系统推荐版本 3.安装驱动，安装指定版本如<code>sudo apt-get install nvidia-driver-470</code>，直接安装系统推荐版本 <code>sudo ubuntu-drivers install</code> 4.如果UEFI模式，需要导入签名。 5.重启系统 <code>reboot</code>，验证是否安装成功 <code>sudo nvidia-smi</code>
|-
| NVIDIA官网驱动安装
|
|-
|
|
|}

{{了解更多
|[https://www.itzgeek.com/post/how-to-install-nvidia-drivers-on-ubuntu-20-04-ubuntu-18-04.html itzgeek.com：如何在 Ubuntu 20.04 和 Ubuntu 18.04 安装NVIDIA驱动]
|[https://ubuntu.com/blog/how-to-sign-things-for-secure-boot Ubuntu 博客：Secure Boot模式下如何签名]
|[https://askubuntu.com/questions/1023036/how-to-install-nvidia-driver-with-secure-boot-enabled askubuntu.com：Secure Boot模式下如何安装NVIDIA驱动]
|[https://askubuntu.com/questions/762254/why-do-i-get-required-key-not-available-when-install-3rd-party-kernel-modules/762255#762255 askubuntu.com：https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues]
}}

==安全设置==

====常见问题====
I: The initramfs will attempt to resume from /dev/sda2
<syntaxhighlight lang="bash">
blkid | awk -F\" '/swap/ {print $2}'
printf "RESUME=UUID=$(blkid | awk -F\" '/swap/ {print $2}')\n" | sudo tee /etc/initramfs-tools/conf.d/resume
sudo update-initramfs -u -k all
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues askubuntu.com：]
}}

== 备份与还原 ==
=== 使用dd备份还原 ===
关机，插入ubuntu安装u盘，进入试用系统，dd命令镜像硬盘，配合gzip压缩文件，多核cpu可以使用pigz并行压缩更快。一般备份<code>/boot/efi</code>、
<code>/</code> 、<code>/home</code> 所在分区。

测试环境：系统盘在Samsung SSD 980 1TB，备份位置在西部2TB黑盘7200转（WD2003FZEX），
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 不使用压缩，分区多大，生成文件就多大。
sudo dd if=/dev/nvme0n1p1 of=/media/ubuntu/newpan/nvme0n1p1.img bs=64M status=progress

# 使用dd和pigz
# nvme0n1p2为ssd硬盘分区，保存分区newpan为HDD硬盘，12核cpu使用pigz压缩
# /分区 100G，压缩后6.5G，总用时152s，速度约为673MB/s，测试bs=128M用时还多27s。
sudo apt install pigz
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | pigz -3 -p 12 > /media/ubuntu/newpan/nvme0n1p2.20250101.img.gz

# 使用dd和gzip
# 速度比pigz慢10多倍，大约50MB/s
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | gzip -c > /media/ubuntu/newpan/nvme0n1p2.20250102.img.gz
</syntaxhighlight>

还原
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 使用dd和gzip
# img.gz文件大小10.8G，块大小100G，用时327s，速度约306MB/s
sudo gzip -d -c nvme0n1p2.20250101.img.gz | sudo dd of=/dev/nvme0n1p2 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync

# 使用dd和pigz，速度与gzip差不多，
# 15.3G 82G 276s 296MB/s
sudo apt install pigz
sudo pigz -d -c -p 12 nvme0n1p5.20250101.img.gz | sudo dd of=/dev/nvme0n1p5 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync
</syntaxhighlight>

=== 备份软件 ===
{| class="wikitable" style="width: 100%;
! 名称
! 接口
! 级别
! 描述
! 网站
|-
| Déjà Dup
| 图形界面
| 文件
| Ubuntu的默认桌面备份管理器，桌面左上角点击Activities，搜索<code>backups</code>可以找到。
| [https://wiki.gnome.org/Apps/DejaDup gnome]
|-
| tar
| 命令行
| 文件
|
|
|-
| rsync
| 命令行
| 文件
|
|
|-
| dd
| 命令行
| 硬盘
| 使用dd镜像硬盘，配合gzip压缩文件。不能使用dd备份当前正在使用的块存储设备，会导致文件系统上的不一致。
|
|-
| [[clonezilla]]
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|-
| [[partclone]]
| 命令行
| 硬盘
| 系统备份还原软件。clonezilla开发，clonezilla也默认使用partclone备份。
|
|-
| TimeShift
| 图形界面
|
| 系统备份还原软件。
|
|-
| systemback
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|}

{{了解更多
|[https://help.ubuntu.com/community/BackupYourSystem Ubuntu 社区wiki：备份你的系统]
|[https://en.wikipedia.org/wiki/List_of_backup_software 维基百科：备份软件列表]
|[https://www.dell.com/support/kbdoc/zh-cn/000152034/如何使用Ubuntu Linux备份实用程序备份戴尔PC ]
}}

==常见问题==
===显示问题===
1.屏幕偶尔几秒黑屏一下。

2.黑屏后无法唤起。

===声音问题===
1.USB耳机或音响没声音
设置》声音》选择输出设备，如果3.5mm接口输出，选择线缆输出built-in Audio。

或者
*在终端输入<code>alsamixer</code>命令，打开AlsaMixer
*按F6选择声卡
*查看声音设备的id：<code>cat /proc/asound/cards</code>
*打开<code>sudo gpedit /etc/asound.conf</code>，根据声卡id设置默认声卡。
<syntaxhighlight lang="bash">
defaults.ctl.card 2
defaults.pcm.card 2
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/447718/no-sound-on-usb-headset-how-to-manage-soundcards-and-audio-devices askubuntu.com：USB耳机上没有声音，如何管理声卡和音频设备？]
}}

===系统程序出现问题===
桌面版，有时会弹出”检测到系统程序出现问题“面板。
<syntaxhighlight lang="bash" >
# 列出存储系统或应用程序崩溃时生成的崩溃报告
ls -al /var/crash/

# 查看崩溃报告内容，如_bin_brltty.0.crash
less /var/crash/_bin_brltty.0.crash

# 修复导致崩溃的问题
# 1.更新系统
sudo apt update && sudo apt upgrade
# 2.检查具体程序，删除或者重新安装，比如brltty盲文显示器程序
sudo apt remove brltty # 删除brltty
sudo apt install --reinstall brltty # 如果brltty需要重新安装brltty
# 查看系统日志，获取更多信息，搜索相关内容
journalctl -p err
grep -i error /var/log/syslog

# 删除崩溃报告
sudo rm /var/crash/_bin_brltty.0.crash

# 提交给Ubuntu的开发者
apport-cli /var/crash/_bin_brltty.0.crash
</syntaxhighlight>

如果崩溃仍然存在，而且不需要提醒，可以禁用Apport。
<syntaxhighlight lang="bash" >
sudo vim /etc/default/apport

# 将配置文件enabled=1 改为enabled=0，并保存

# 重启电脑
sudo reboot

</syntaxhighlight>

注意事项：
* 崩溃报告可能包含敏感信息，因此在提交之前请确保你了解报告的内容。
* 如果你经常遇到某个应用程序崩溃，建议检查是否有更新版本可用，或者查看相关的支持论坛以获取帮助。

===启动慢===
使用 systemd-analyze 查看详细耗时：
<syntaxhighlight lang="bash" >
systemd-analyze time # 总时间
systemd-analyze blame # 按耗时排序的服务
systemd-analyze critical-chain # 关键依赖链
</syntaxhighlight>

移除 quiet splash 可看到详细启动日志，观察卡在哪：
<syntaxhighlight lang="bash" >
sudo nano /etc/default/grub
# 暂时去掉 quiet splash
# GRUB_CMDLINE_LINUX_DEFAULT=""

sudo update-grub
</syntaxhighlight>

==资源==
===官网===
*Ubuntu 官网：https://ubuntu.com/
*Ubuntu 文档：https://help.ubuntu.com/
*Ubuntu 社区wiki：https://help.ubuntu.com/community/CommunityHelpWiki
*Ubuntu 桌面指南：https://help.ubuntu.com/stable/ubuntu-help/index.html.zh-CN

===相关网页===
*[https://zh.wikipedia.org/zh-cn/Ubuntu 维基百科：Ubuntu]

[[分类:系统软件]]

Ubuntu

2026-04-27T15:47:53Z

Eric：/* 快捷方式 */

Ubuntu是一个[[Linux]]的发行版，由Canonical公司发布并提供商业支持。Ubuntu项目公开承诺开源软件开发的原则；鼓励人们使用自由软件，研究它的运作原理，改进和分发。Ubuntu是著名的[[Linux]]发行版之一，基于[[Debian]]发行版和GNOME桌面环境。

==简介==
===时间轴===
*2004年10月20日，马克·舍特尔沃斯创立并发布Ubuntu第一个版本Ubuntu 4.10，它以Debian为开发蓝本。
*2005年7月8日，马克·舍特尔沃斯与Canonical有限公司宣布成立Ubuntu基金会，并提供1千万美元作为启始营运资金。但直至2006年，此基金会仍未投入运作。马克·舍特尔沃斯形容此基金会是在Canonical有限公司出现财务危机时的紧急营运资金。

===版本===

===安装===
====制作启动U盘====
Ubuntu官网下载ISO镜像。

linux中制作启动U盘：
方法一：使用dd命令，一定要注意看清楚哪个盘，不然可能格式化错盘。
<syntaxhighlight lang="bash">
# 插入u盘，查看所有块设备：
lsblk

# 使用dd命令写入ISO到U盘，如u盘为sdx：
sudo dd if=/path/to/ubuntu.iso of=/dev/sdx bs=4M status=progress

# 安全移除U盘
sudo eject /dev/sdx
</syntaxhighlight>

windows中制作启动U盘：
方法一，Ubuntu官方教程使用[[Rufus]]软件制作启动U盘，下面使用[[UltraISO]]软件制作启动U盘，只是写启动盘可以用试用版。
*打开UltraISO，选择下载好的Ubuntu系统
*点击菜单栏‘启动’》‘写入硬盘映像’
*在对话框的‘硬盘驱动器’处选择要刻录的U盘
*然后点击‘写入’，注意U盘会被格式化所有资料都没有
*启动U盘制作完成，可以用它在任何电脑安装Ubuntu

方法二，也可以使用<code>diskpart</code>和<code>xcopy</code>命令行制作ubuntu的启动U盘，在如下：
* 搜索框输入<code>cmd</code>，打开命令提示符。
* 在cmd中输入<code>diskpart</code> ，打开磁盘管理。
* <code>list disk</code>，查看所有磁盘信息。
* <code>select disk 2</code>，选择U盘，示例U盘为disk 2。
* <code>clean</code>，清除U盘。
* <code>create partition primary</code>，创建分区。
* <code>select partition 1</code>，选择分区1。
* <code>active</code>，将当前分区标记为活动。
* <code>format fs=ntfs quick</code>，格式化分区为ntfs格式。
* <code>assign</code>，分配盘符。
* <code>exit</code>，退出。
* 选择下载好的iso文件，右键点击装载。查看装载后的盘符，如<code>G：</code>
* <code>xcopy G:\*.* /e /h /f H:\</code>，复制所有文件到U盘。其中<code>H:</code>为U盘的盘符。<code>/e</code>复制所有子目录，即使它们是空的。<code>/h</code>复制具有隐藏文件和系统文件属性的文件。 <code>/f</code>复制时显示源文件名和目标文件名。

{{了解更多
|[https://ubuntu.com/tutorials/tutorial-create-a-usb-stick-on-windows#1-overview Ubuntu 教程：Windows上制作启动U盘]
|[https://learn.microsoft.com/zh-cn/windows-server/administration/windows-commands/xcopy Windows Server文档：xcopy]
}}

====安装到电脑====

====安装到U盘====

====分区方案====
{{Linux分区方案}}
==技巧==
*创建某个目录在桌面快捷方式
点击某个目录，按住Ctrl + Shift，拖动到桌面目录(文件打开)里，注意不能直接拖动到桌面。

==软件==
===软件安装===
====apt====

====deb====

====AppImage====
是Linux上的一种应用打包格式，将程序所有文件打包成一个AppImage，可以在不同Linux发行版上运行。直接运行，不需要安装运行库。

运行AppImage格式程序
<syntaxhighlight lang="bash" >
# 进入AppImage 文件所在目录，为文件添加可执行权限
cd /path/to/directory
chmod +x example.AppImage

# 直接运行文件
./example.AppImage
</syntaxhighlight>

===快捷方式===
应用程序和桌面创建快捷方式。.desktop 文件是 Linux 桌面环境中用于定义应用程序启动器、菜单项或快捷方式的配置文件。常用文件内容如下：
*Name：应用程序的显示名称（必填）。
*Exec：启动应用程序的命令（必填），路径使用绝对路径。
*Type：定义文件类型，常见值：Application：应用程序，Link：快捷方式，Directory：目录
*Icon：Ubuntu支持的图标格式包括 PNG、SVG、XPM。注意路径最后面不要有空格，否则图标不会显示。图标可以在提取文件里找<code>./example.AppImage --appimage-extract</code>
<syntaxhighlight lang="bash" >
# 创建 .desktop 文件
vim ~/.local/share/applications/example.desktop

# 编辑 .desktop 文件内容
[Desktop Entry]
Name=Example App
Exec=/path/to/example.AppImage
Type=Application
Terminal=false
Icon=/path/to/icon.png
Comment=Example App Shortcut
Categories=Utility;

# 保存并赋予权限
chmod +x ~/.local/share/applications/example.desktop

# 复制到桌面
# 桌面上点击图标，右键，点击允许运行
cp ~/.local/share/applications/example.desktop ~/Desktop/
</syntaxhighlight>

====Edge多个用户启动====
Edge地址栏输入并访问 edge://version/，找到 "个人资料路径" 这一栏。路径末尾的 Default 就是你的默认用户的目录名。第二个用户通常名为 Profile 1、Profile 2，或是你自定义的名称。示例，创建不同的 .desktop 文件，启动时指定不同Edge用户：
nano ~/.local/share/applications/edge-profile1.desktop
输入如下内容，ctrl+o保存，ctrl+x退出：
<syntaxhighlight lang="bash" >
[Desktop Entry]
Type=Application
Name=Edge 用户1
Exec=/usr/bin/microsoft-edge --profile-directory="Profile 1"
# 或者Icon=/path/to/microsoft-edge.Profile1.png
Icon=microsoft-edge
Terminal=false
Comment=使用个人资料1打开Microsoft Edge
# Categories=Network;
# StartupWMClass=edge-profile1 # 用于区分窗口

</syntaxhighlight>
点击系统菜单，显示所有应用，找到刚才命名的名字“Edge - 用户1”，右键点击它的图标，选择“添加到收藏夹”或“添加到Dock”。

===常用软件===
{| class="wikitable" style="width: 100%;
! 名称
! 描述
! 网址
|-
| [[KVM]]
|
|
|-
| [[VLC]]
| VLC是一款开源的、免费的多平台视频播放器，支持MPEG-2, MPEG-4, H.264, MKV, WebM, WMV, MP3等格式。安装命令：sudo apt install vlc
| [https://www.videolan.org/vlc/ 官网]
|-
| [[VMware Workstation]]
|
| [https://www.vmware.com/products/workstation-pro.html 官网] [https://www.vmware.com/products/workstation-pro/workstation-pro-evaluation.html 下载]
|-
| WPS
| 金山办公套装软件,支持多人在线协作编辑Word、Excel和PPT文档。 安装： 常见问题： *缺少系统字体：Symbol、Wingdings 1、Wingdings 2、Wingdings 3、Webdings、MT Extra， WPS无法正确地显示某些符号公式。因为这些字体是 Microsoft Windows 系统中的专有字体，而 Ubuntu 默认并未包含它们。 解决方法： 1.下载字体，从windows中复制字体C:\Windows\Fonts，或者web上搜索字体下载，或者从https://github.com/dv-anomaly/ttf-wps-fonts。 2.安在到系统中，
<syntaxhighlight lang="bash" >
sudo mkdir -p /usr/share/fonts/wps-office
cd ~/Downloads/ttf-wps-fonts-master # 进入下载好的目录
sudo cp mtextra.ttf symbol.ttf wingding.ttf WINGDNG3.ttf WEBDINGS.TTF WINGDNG2.ttf /usr/share/fonts/wps-office/
sudo fc-cache -fv
</syntaxhighlight>
|[https://platform.wps.cn/ 下载]
|-
| [[IBus]]
| Ubuntu 24.04及其他各大[[Linux]]发行版的默认的多语输入平台。支持用户词典、用户lua脚本。
| [https://github.com/ibus/ibus/wiki 官网]
|-
| [[搜狗输入法]]
| 有自定义短语功能，支持多行空格等。Windows上有广告弹窗，安装其他软件。 安装： 1.安装fcitx。<code>sudo apt-get install fcitx</code> 2.添加中文语言支持 3.下载安装搜狗输入法。<code>sudo dpkg -i sogoupinyin_版本号_amd64.deb</code> 。如果安装过程提示缺少依赖<code>sudo apt -f install</code> 设置为默认输入法，点击桌面右上角键盘图标->设置(Configure)->Input Method将sougoupinyin移动到最上边。
| [https://pinyin.sogou.com/linux/ 官网] [https://pinyin.sogou.com/linux/help.php 安装指南]
|-
| 网易音乐
| 安装： 1.点击下载客户端，其他操作系统客户端，Linux版 2.双击下载的deb文件安装
| [https://music.163.com/ 官网] [https://music.163.com/#/download 下载]
|-
| qq音乐
|
| [https://y.qq.com/download/download.html 下载]
|-
| [[Conky]]
| 桌面环境的系统监控工具。免费开源，高度可定制。 安装：<code>sudo apt-get install conky</code>
| [https://github.com/brndnmtthws/conky 官网]
|-
| btop
|
|
|}

==用户管理==

==网络设置==
===防火墙设置===

==安装驱动==
===显卡驱动===
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| Ubuntu软件库安装
| 推荐方法，简单快捷可更新。 安装步骤： 1.更新软件库 <code>sudo apt-get update</code> 2.查找相关驱动 <code>sudo ubuntu-drivers devices</code> ，后面带recommend是系统推荐版本 3.安装驱动，安装指定版本如<code>sudo apt-get install nvidia-driver-470</code>，直接安装系统推荐版本 <code>sudo ubuntu-drivers install</code> 4.如果UEFI模式，需要导入签名。 5.重启系统 <code>reboot</code>，验证是否安装成功 <code>sudo nvidia-smi</code>
|-
| NVIDIA官网驱动安装
|
|-
|
|
|}

{{了解更多
|[https://www.itzgeek.com/post/how-to-install-nvidia-drivers-on-ubuntu-20-04-ubuntu-18-04.html itzgeek.com：如何在 Ubuntu 20.04 和 Ubuntu 18.04 安装NVIDIA驱动]
|[https://ubuntu.com/blog/how-to-sign-things-for-secure-boot Ubuntu 博客：Secure Boot模式下如何签名]
|[https://askubuntu.com/questions/1023036/how-to-install-nvidia-driver-with-secure-boot-enabled askubuntu.com：Secure Boot模式下如何安装NVIDIA驱动]
|[https://askubuntu.com/questions/762254/why-do-i-get-required-key-not-available-when-install-3rd-party-kernel-modules/762255#762255 askubuntu.com：https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues]
}}

==安全设置==

====常见问题====
I: The initramfs will attempt to resume from /dev/sda2
<syntaxhighlight lang="bash">
blkid | awk -F\" '/swap/ {print $2}'
printf "RESUME=UUID=$(blkid | awk -F\" '/swap/ {print $2}')\n" | sudo tee /etc/initramfs-tools/conf.d/resume
sudo update-initramfs -u -k all
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues askubuntu.com：]
}}

== 备份与还原 ==
=== 使用dd备份还原 ===
关机，插入ubuntu安装u盘，进入试用系统，dd命令镜像硬盘，配合gzip压缩文件，多核cpu可以使用pigz并行压缩更快。一般备份<code>/boot/efi</code>、
<code>/</code> 、<code>/home</code> 所在分区。

测试环境：系统盘在Samsung SSD 980 1TB，备份位置在西部2TB黑盘7200转（WD2003FZEX），
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 不使用压缩，分区多大，生成文件就多大。
sudo dd if=/dev/nvme0n1p1 of=/media/ubuntu/newpan/nvme0n1p1.img bs=64M status=progress

# 使用dd和pigz
# nvme0n1p2为ssd硬盘分区，保存分区newpan为HDD硬盘，12核cpu使用pigz压缩
# /分区 100G，压缩后6.5G，总用时152s，速度约为673MB/s，测试bs=128M用时还多27s。
sudo apt install pigz
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | pigz -3 -p 12 > /media/ubuntu/newpan/nvme0n1p2.20250101.img.gz

# 使用dd和gzip
# 速度比pigz慢10多倍，大约50MB/s
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | gzip -c > /media/ubuntu/newpan/nvme0n1p2.20250102.img.gz
</syntaxhighlight>

还原
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 使用dd和gzip
# img.gz文件大小10.8G，块大小100G，用时327s，速度约306MB/s
sudo gzip -d -c nvme0n1p2.20250101.img.gz | sudo dd of=/dev/nvme0n1p2 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync

# 使用dd和pigz，速度与gzip差不多，
# 15.3G 82G 276s 296MB/s
sudo apt install pigz
sudo pigz -d -c -p 12 nvme0n1p5.20250101.img.gz | sudo dd of=/dev/nvme0n1p5 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync
</syntaxhighlight>

=== 备份软件 ===
{| class="wikitable" style="width: 100%;
! 名称
! 接口
! 级别
! 描述
! 网站
|-
| Déjà Dup
| 图形界面
| 文件
| Ubuntu的默认桌面备份管理器，桌面左上角点击Activities，搜索<code>backups</code>可以找到。
| [https://wiki.gnome.org/Apps/DejaDup gnome]
|-
| tar
| 命令行
| 文件
|
|
|-
| rsync
| 命令行
| 文件
|
|
|-
| dd
| 命令行
| 硬盘
| 使用dd镜像硬盘，配合gzip压缩文件。不能使用dd备份当前正在使用的块存储设备，会导致文件系统上的不一致。
|
|-
| [[clonezilla]]
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|-
| [[partclone]]
| 命令行
| 硬盘
| 系统备份还原软件。clonezilla开发，clonezilla也默认使用partclone备份。
|
|-
| TimeShift
| 图形界面
|
| 系统备份还原软件。
|
|-
| systemback
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|}

{{了解更多
|[https://help.ubuntu.com/community/BackupYourSystem Ubuntu 社区wiki：备份你的系统]
|[https://en.wikipedia.org/wiki/List_of_backup_software 维基百科：备份软件列表]
|[https://www.dell.com/support/kbdoc/zh-cn/000152034/如何使用Ubuntu Linux备份实用程序备份戴尔PC ]
}}

==常见问题==
===显示问题===
1.屏幕偶尔几秒黑屏一下。

2.黑屏后无法唤起。

===声音问题===
1.USB耳机或音响没声音
设置》声音》选择输出设备，如果3.5mm接口输出，选择线缆输出built-in Audio。

或者
*在终端输入<code>alsamixer</code>命令，打开AlsaMixer
*按F6选择声卡
*查看声音设备的id：<code>cat /proc/asound/cards</code>
*打开<code>sudo gpedit /etc/asound.conf</code>，根据声卡id设置默认声卡。
<syntaxhighlight lang="bash">
defaults.ctl.card 2
defaults.pcm.card 2
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/447718/no-sound-on-usb-headset-how-to-manage-soundcards-and-audio-devices askubuntu.com：USB耳机上没有声音，如何管理声卡和音频设备？]
}}

===系统程序出现问题===
桌面版，有时会弹出”检测到系统程序出现问题“面板。
<syntaxhighlight lang="bash" >
# 列出存储系统或应用程序崩溃时生成的崩溃报告
ls -al /var/crash/

# 查看崩溃报告内容，如_bin_brltty.0.crash
less /var/crash/_bin_brltty.0.crash

# 修复导致崩溃的问题
# 1.更新系统
sudo apt update && sudo apt upgrade
# 2.检查具体程序，删除或者重新安装，比如brltty盲文显示器程序
sudo apt remove brltty # 删除brltty
sudo apt install --reinstall brltty # 如果brltty需要重新安装brltty
# 查看系统日志，获取更多信息，搜索相关内容
journalctl -p err
grep -i error /var/log/syslog

# 删除崩溃报告
sudo rm /var/crash/_bin_brltty.0.crash

# 提交给Ubuntu的开发者
apport-cli /var/crash/_bin_brltty.0.crash
</syntaxhighlight>

如果崩溃仍然存在，而且不需要提醒，可以禁用Apport。
<syntaxhighlight lang="bash" >
sudo vim /etc/default/apport

# 将配置文件enabled=1 改为enabled=0，并保存

# 重启电脑
sudo reboot

</syntaxhighlight>

注意事项：
* 崩溃报告可能包含敏感信息，因此在提交之前请确保你了解报告的内容。
* 如果你经常遇到某个应用程序崩溃，建议检查是否有更新版本可用，或者查看相关的支持论坛以获取帮助。

==资源==
===官网===
*Ubuntu 官网：https://ubuntu.com/
*Ubuntu 文档：https://help.ubuntu.com/
*Ubuntu 社区wiki：https://help.ubuntu.com/community/CommunityHelpWiki
*Ubuntu 桌面指南：https://help.ubuntu.com/stable/ubuntu-help/index.html.zh-CN

===相关网页===
*[https://zh.wikipedia.org/zh-cn/Ubuntu 维基百科：Ubuntu]

[[分类:系统软件]]

Ubuntu

2026-04-27T15:00:46Z

Eric：/* 软件 */

Ubuntu是一个[[Linux]]的发行版，由Canonical公司发布并提供商业支持。Ubuntu项目公开承诺开源软件开发的原则；鼓励人们使用自由软件，研究它的运作原理，改进和分发。Ubuntu是著名的[[Linux]]发行版之一，基于[[Debian]]发行版和GNOME桌面环境。

==简介==
===时间轴===
*2004年10月20日，马克·舍特尔沃斯创立并发布Ubuntu第一个版本Ubuntu 4.10，它以Debian为开发蓝本。
*2005年7月8日，马克·舍特尔沃斯与Canonical有限公司宣布成立Ubuntu基金会，并提供1千万美元作为启始营运资金。但直至2006年，此基金会仍未投入运作。马克·舍特尔沃斯形容此基金会是在Canonical有限公司出现财务危机时的紧急营运资金。

===版本===

===安装===
====制作启动U盘====
Ubuntu官网下载ISO镜像。

linux中制作启动U盘：
方法一：使用dd命令，一定要注意看清楚哪个盘，不然可能格式化错盘。
<syntaxhighlight lang="bash">
# 插入u盘，查看所有块设备：
lsblk

# 使用dd命令写入ISO到U盘，如u盘为sdx：
sudo dd if=/path/to/ubuntu.iso of=/dev/sdx bs=4M status=progress

# 安全移除U盘
sudo eject /dev/sdx
</syntaxhighlight>

windows中制作启动U盘：
方法一，Ubuntu官方教程使用[[Rufus]]软件制作启动U盘，下面使用[[UltraISO]]软件制作启动U盘，只是写启动盘可以用试用版。
*打开UltraISO，选择下载好的Ubuntu系统
*点击菜单栏‘启动’》‘写入硬盘映像’
*在对话框的‘硬盘驱动器’处选择要刻录的U盘
*然后点击‘写入’，注意U盘会被格式化所有资料都没有
*启动U盘制作完成，可以用它在任何电脑安装Ubuntu

方法二，也可以使用<code>diskpart</code>和<code>xcopy</code>命令行制作ubuntu的启动U盘，在如下：
* 搜索框输入<code>cmd</code>，打开命令提示符。
* 在cmd中输入<code>diskpart</code> ，打开磁盘管理。
* <code>list disk</code>，查看所有磁盘信息。
* <code>select disk 2</code>，选择U盘，示例U盘为disk 2。
* <code>clean</code>，清除U盘。
* <code>create partition primary</code>，创建分区。
* <code>select partition 1</code>，选择分区1。
* <code>active</code>，将当前分区标记为活动。
* <code>format fs=ntfs quick</code>，格式化分区为ntfs格式。
* <code>assign</code>，分配盘符。
* <code>exit</code>，退出。
* 选择下载好的iso文件，右键点击装载。查看装载后的盘符，如<code>G：</code>
* <code>xcopy G:\*.* /e /h /f H:\</code>，复制所有文件到U盘。其中<code>H:</code>为U盘的盘符。<code>/e</code>复制所有子目录，即使它们是空的。<code>/h</code>复制具有隐藏文件和系统文件属性的文件。 <code>/f</code>复制时显示源文件名和目标文件名。

{{了解更多
|[https://ubuntu.com/tutorials/tutorial-create-a-usb-stick-on-windows#1-overview Ubuntu 教程：Windows上制作启动U盘]
|[https://learn.microsoft.com/zh-cn/windows-server/administration/windows-commands/xcopy Windows Server文档：xcopy]
}}

====安装到电脑====

====安装到U盘====

====分区方案====
{{Linux分区方案}}
==技巧==
*创建某个目录在桌面快捷方式
点击某个目录，按住Ctrl + Shift，拖动到桌面目录(文件打开)里，注意不能直接拖动到桌面。

==软件==
===软件安装===
====apt====

====deb====

====AppImage====
是Linux上的一种应用打包格式，将程序所有文件打包成一个AppImage，可以在不同Linux发行版上运行。直接运行，不需要安装运行库。

运行AppImage格式程序
<syntaxhighlight lang="bash" >
# 进入AppImage 文件所在目录，为文件添加可执行权限
cd /path/to/directory
chmod +x example.AppImage

# 直接运行文件
./example.AppImage
</syntaxhighlight>

===快捷方式===
应用程序和桌面创建快捷方式。.desktop 文件是 Linux 桌面环境中用于定义应用程序启动器、菜单项或快捷方式的配置文件。常用文件内容如下：
*Name：应用程序的显示名称（必填）。
*Exec：启动应用程序的命令（必填），路径使用绝对路径。
*Type：定义文件类型，常见值：Application：应用程序，Link：快捷方式，Directory：目录
*Icon：Ubuntu支持的图标格式包括 PNG、SVG、XPM。注意路径最后面不要有空格，否则图标不会显示。图标可以在提取文件里找<code>./example.AppImage --appimage-extract</code>
<syntaxhighlight lang="bash" >
# 创建 .desktop 文件
vim ~/.local/share/applications/example.desktop

# 编辑 .desktop 文件内容
[Desktop Entry]
Name=Example App
Exec=/path/to/example.AppImage
Type=Application
Terminal=false
Icon=/path/to/icon.png
Comment=Example App Shortcut
Categories=Utility;

# 保存并赋予权限
chmod +x ~/.local/share/applications/example.desktop

# 复制到桌面
# 桌面上点击图标，右键，点击允许运行
cp ~/.local/share/applications/example.desktop ~/Desktop/
</syntaxhighlight>

===常用软件===
{| class="wikitable" style="width: 100%;
! 名称
! 描述
! 网址
|-
| [[KVM]]
|
|
|-
| [[VLC]]
| VLC是一款开源的、免费的多平台视频播放器，支持MPEG-2, MPEG-4, H.264, MKV, WebM, WMV, MP3等格式。安装命令：sudo apt install vlc
| [https://www.videolan.org/vlc/ 官网]
|-
| [[VMware Workstation]]
|
| [https://www.vmware.com/products/workstation-pro.html 官网] [https://www.vmware.com/products/workstation-pro/workstation-pro-evaluation.html 下载]
|-
| WPS
| 金山办公套装软件,支持多人在线协作编辑Word、Excel和PPT文档。 安装： 常见问题： *缺少系统字体：Symbol、Wingdings 1、Wingdings 2、Wingdings 3、Webdings、MT Extra， WPS无法正确地显示某些符号公式。因为这些字体是 Microsoft Windows 系统中的专有字体，而 Ubuntu 默认并未包含它们。 解决方法： 1.下载字体，从windows中复制字体C:\Windows\Fonts，或者web上搜索字体下载，或者从https://github.com/dv-anomaly/ttf-wps-fonts。 2.安在到系统中，
<syntaxhighlight lang="bash" >
sudo mkdir -p /usr/share/fonts/wps-office
cd ~/Downloads/ttf-wps-fonts-master # 进入下载好的目录
sudo cp mtextra.ttf symbol.ttf wingding.ttf WINGDNG3.ttf WEBDINGS.TTF WINGDNG2.ttf /usr/share/fonts/wps-office/
sudo fc-cache -fv
</syntaxhighlight>
|[https://platform.wps.cn/ 下载]
|-
| [[IBus]]
| Ubuntu 24.04及其他各大[[Linux]]发行版的默认的多语输入平台。支持用户词典、用户lua脚本。
| [https://github.com/ibus/ibus/wiki 官网]
|-
| [[搜狗输入法]]
| 有自定义短语功能，支持多行空格等。Windows上有广告弹窗，安装其他软件。 安装： 1.安装fcitx。<code>sudo apt-get install fcitx</code> 2.添加中文语言支持 3.下载安装搜狗输入法。<code>sudo dpkg -i sogoupinyin_版本号_amd64.deb</code> 。如果安装过程提示缺少依赖<code>sudo apt -f install</code> 设置为默认输入法，点击桌面右上角键盘图标->设置(Configure)->Input Method将sougoupinyin移动到最上边。
| [https://pinyin.sogou.com/linux/ 官网] [https://pinyin.sogou.com/linux/help.php 安装指南]
|-
| 网易音乐
| 安装： 1.点击下载客户端，其他操作系统客户端，Linux版 2.双击下载的deb文件安装
| [https://music.163.com/ 官网] [https://music.163.com/#/download 下载]
|-
| qq音乐
|
| [https://y.qq.com/download/download.html 下载]
|-
| [[Conky]]
| 桌面环境的系统监控工具。免费开源，高度可定制。 安装：<code>sudo apt-get install conky</code>
| [https://github.com/brndnmtthws/conky 官网]
|-
| btop
|
|
|}

==用户管理==

==网络设置==
===防火墙设置===

==安装驱动==
===显卡驱动===
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| Ubuntu软件库安装
| 推荐方法，简单快捷可更新。 安装步骤： 1.更新软件库 <code>sudo apt-get update</code> 2.查找相关驱动 <code>sudo ubuntu-drivers devices</code> ，后面带recommend是系统推荐版本 3.安装驱动，安装指定版本如<code>sudo apt-get install nvidia-driver-470</code>，直接安装系统推荐版本 <code>sudo ubuntu-drivers install</code> 4.如果UEFI模式，需要导入签名。 5.重启系统 <code>reboot</code>，验证是否安装成功 <code>sudo nvidia-smi</code>
|-
| NVIDIA官网驱动安装
|
|-
|
|
|}

{{了解更多
|[https://www.itzgeek.com/post/how-to-install-nvidia-drivers-on-ubuntu-20-04-ubuntu-18-04.html itzgeek.com：如何在 Ubuntu 20.04 和 Ubuntu 18.04 安装NVIDIA驱动]
|[https://ubuntu.com/blog/how-to-sign-things-for-secure-boot Ubuntu 博客：Secure Boot模式下如何签名]
|[https://askubuntu.com/questions/1023036/how-to-install-nvidia-driver-with-secure-boot-enabled askubuntu.com：Secure Boot模式下如何安装NVIDIA驱动]
|[https://askubuntu.com/questions/762254/why-do-i-get-required-key-not-available-when-install-3rd-party-kernel-modules/762255#762255 askubuntu.com：https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues]
}}

==安全设置==

====常见问题====
I: The initramfs will attempt to resume from /dev/sda2
<syntaxhighlight lang="bash">
blkid | awk -F\" '/swap/ {print $2}'
printf "RESUME=UUID=$(blkid | awk -F\" '/swap/ {print $2}')\n" | sudo tee /etc/initramfs-tools/conf.d/resume
sudo update-initramfs -u -k all
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/1116778/how-to-set-the-resume-variable-to-override-these-issues askubuntu.com：]
}}

== 备份与还原 ==
=== 使用dd备份还原 ===
关机，插入ubuntu安装u盘，进入试用系统，dd命令镜像硬盘，配合gzip压缩文件，多核cpu可以使用pigz并行压缩更快。一般备份<code>/boot/efi</code>、
<code>/</code> 、<code>/home</code> 所在分区。

测试环境：系统盘在Samsung SSD 980 1TB，备份位置在西部2TB黑盘7200转（WD2003FZEX），
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 不使用压缩，分区多大，生成文件就多大。
sudo dd if=/dev/nvme0n1p1 of=/media/ubuntu/newpan/nvme0n1p1.img bs=64M status=progress

# 使用dd和pigz
# nvme0n1p2为ssd硬盘分区，保存分区newpan为HDD硬盘，12核cpu使用pigz压缩
# /分区 100G，压缩后6.5G，总用时152s，速度约为673MB/s，测试bs=128M用时还多27s。
sudo apt install pigz
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | pigz -3 -p 12 > /media/ubuntu/newpan/nvme0n1p2.20250101.img.gz

# 使用dd和gzip
# 速度比pigz慢10多倍，大约50MB/s
sudo dd if=/dev/nvme0n1p2 bs=64M status=progress | gzip -c > /media/ubuntu/newpan/nvme0n1p2.20250102.img.gz
</syntaxhighlight>

还原
<syntaxhighlight lang="bash" >
# 查看磁盘和分区，确定目标
lsblk

# 使用dd和gzip
# img.gz文件大小10.8G，块大小100G，用时327s，速度约306MB/s
sudo gzip -d -c nvme0n1p2.20250101.img.gz | sudo dd of=/dev/nvme0n1p2 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync

# 使用dd和pigz，速度与gzip差不多，
# 15.3G 82G 276s 296MB/s
sudo apt install pigz
sudo pigz -d -c -p 12 nvme0n1p5.20250101.img.gz | sudo dd of=/dev/nvme0n1p5 bs=64M status=progress
# 确保所有数据写入磁盘
sudo sync
</syntaxhighlight>

=== 备份软件 ===
{| class="wikitable" style="width: 100%;
! 名称
! 接口
! 级别
! 描述
! 网站
|-
| Déjà Dup
| 图形界面
| 文件
| Ubuntu的默认桌面备份管理器，桌面左上角点击Activities，搜索<code>backups</code>可以找到。
| [https://wiki.gnome.org/Apps/DejaDup gnome]
|-
| tar
| 命令行
| 文件
|
|
|-
| rsync
| 命令行
| 文件
|
|
|-
| dd
| 命令行
| 硬盘
| 使用dd镜像硬盘，配合gzip压缩文件。不能使用dd备份当前正在使用的块存储设备，会导致文件系统上的不一致。
|
|-
| [[clonezilla]]
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|-
| [[partclone]]
| 命令行
| 硬盘
| 系统备份还原软件。clonezilla开发，clonezilla也默认使用partclone备份。
|
|-
| TimeShift
| 图形界面
|
| 系统备份还原软件。
|
|-
| systemback
| 图形界面
| 硬盘
| 系统备份还原软件。
|
|}

{{了解更多
|[https://help.ubuntu.com/community/BackupYourSystem Ubuntu 社区wiki：备份你的系统]
|[https://en.wikipedia.org/wiki/List_of_backup_software 维基百科：备份软件列表]
|[https://www.dell.com/support/kbdoc/zh-cn/000152034/如何使用Ubuntu Linux备份实用程序备份戴尔PC ]
}}

==常见问题==
===显示问题===
1.屏幕偶尔几秒黑屏一下。

2.黑屏后无法唤起。

===声音问题===
1.USB耳机或音响没声音
设置》声音》选择输出设备，如果3.5mm接口输出，选择线缆输出built-in Audio。

或者
*在终端输入<code>alsamixer</code>命令，打开AlsaMixer
*按F6选择声卡
*查看声音设备的id：<code>cat /proc/asound/cards</code>
*打开<code>sudo gpedit /etc/asound.conf</code>，根据声卡id设置默认声卡。
<syntaxhighlight lang="bash">
defaults.ctl.card 2
defaults.pcm.card 2
</syntaxhighlight>

{{了解更多
|[https://askubuntu.com/questions/447718/no-sound-on-usb-headset-how-to-manage-soundcards-and-audio-devices askubuntu.com：USB耳机上没有声音，如何管理声卡和音频设备？]
}}

===系统程序出现问题===
桌面版，有时会弹出”检测到系统程序出现问题“面板。
<syntaxhighlight lang="bash" >
# 列出存储系统或应用程序崩溃时生成的崩溃报告
ls -al /var/crash/

# 查看崩溃报告内容，如_bin_brltty.0.crash
less /var/crash/_bin_brltty.0.crash

# 修复导致崩溃的问题
# 1.更新系统
sudo apt update && sudo apt upgrade
# 2.检查具体程序，删除或者重新安装，比如brltty盲文显示器程序
sudo apt remove brltty # 删除brltty
sudo apt install --reinstall brltty # 如果brltty需要重新安装brltty
# 查看系统日志，获取更多信息，搜索相关内容
journalctl -p err
grep -i error /var/log/syslog

# 删除崩溃报告
sudo rm /var/crash/_bin_brltty.0.crash

# 提交给Ubuntu的开发者
apport-cli /var/crash/_bin_brltty.0.crash
</syntaxhighlight>

如果崩溃仍然存在，而且不需要提醒，可以禁用Apport。
<syntaxhighlight lang="bash" >
sudo vim /etc/default/apport

# 将配置文件enabled=1 改为enabled=0，并保存

# 重启电脑
sudo reboot

</syntaxhighlight>

注意事项：
* 崩溃报告可能包含敏感信息，因此在提交之前请确保你了解报告的内容。
* 如果你经常遇到某个应用程序崩溃，建议检查是否有更新版本可用，或者查看相关的支持论坛以获取帮助。

==资源==
===官网===
*Ubuntu 官网：https://ubuntu.com/
*Ubuntu 文档：https://help.ubuntu.com/
*Ubuntu 社区wiki：https://help.ubuntu.com/community/CommunityHelpWiki
*Ubuntu 桌面指南：https://help.ubuntu.com/stable/ubuntu-help/index.html.zh-CN

===相关网页===
*[https://zh.wikipedia.org/zh-cn/Ubuntu 维基百科：Ubuntu]

[[分类:系统软件]]

KVM虚拟机

2026-04-27T14:41:04Z

Eric：/* 配置桥接网路 */

Git

2026-04-21T03:40:58Z

Eric：

git是一个分布式版本控制软件，最初由[[林纳斯·托瓦兹]]创作，于2005年以GPL发布。最初目的是为更好地管理[[Linux]]内核开发而设计。

==简介==
===时间轴===
*2002年，林纳斯·托瓦兹决定使用BitKeeper作为Linux内核主要的版本控制系统用以维护代码。
*2005年，Andrew Tridgell违反的BitKeeper使用原则，进行逆向工程，导致无偿使用BitKeeper的许可被收回。林纳斯·托瓦兹决定自行开发版本控制系统替代BitKeeper，以十天的时间编写出git第一个版本。
*2005年07月11日，发布git 0.99 版
*2005年12月21日，发布git 1.0 版
*2014年05年28日，发布git 2.0 版
*2020年03月23日，发布git 2.26 版

=== 仓库托管服务 ===
很多公司提供了Git仓库的托管服务。
{| class="wikitable"
! 名称
! 公司
! 描述
|-
| [[GitHub]]
| 微软
| 提供付费账户和免费账户，都可以建立公开或私有的代码仓。。截止2023年，Github是世界上最大的代码托管网站和开源社区。
|-
| [[CODING]]
| 腾讯
| 提供付费账户和免费账户
|-
| [[GitLab]]
| GitLab
|
|-
| Gitee
| OSCHINA
|
|}

=== 安装 ===
Linux中一般默认已经按照git， Windows中安装如下；
*1.下载安装程序，https://git-scm.com/download/win
*2.点击安装
{{了解更多
|[https://git-scm.com/book/zh/v2/%E8%B5%B7%E6%AD%A5-%E5%AE%89%E8%A3%85-Git 《Pro Git》中文版V2：1.5 起步 - 安装 Git]
}}

== 快速入门 ==
=== 基本原理 ===
{{#drawio:git工作原理}}
{{了解更多
|[https://git-scm.com/book/zh/v2/起步-Git-是什么？《Pro Git》中文版V2：起步-Git-是什么？]
}}

=== 使用示例 ===
<syntaxhighlight lang="bash" >
# 设置一次Git的全局用户名和邮箱
git config --global user.name "Your Name"
git config --global user.email yourname@example.com

# 在一个目录下，初始化git仓库
# 会在该目录自动生成一个.git目录
git init

</syntaxhighlight>

=== .git 目录 ===
所有git工作目录下都有个<code>.git</code>目录，该目录包含几乎所有git操作和数据内容。当使用<code>git init</code>初始化目录会自动生成该文件夹。
{| class="wikitable"
! 名称
! 描述
|-
| config
| 该项目的特有配置，
|-
|
|
|-
|
|
|}

{{了解更多
|[https://git-scm.com/book/zh/v2/Git-内部原理-底层命令与上层命令《Pro Git》中文版V2：10.1 Git 内部原理 - 底层命令与上层命令]
}}

==命令==
===配置===
{| class="wikitable"
|-
! 命令
! 描述
|-
|查看配置
|<code>git config --list</code>查看所有配置信息 <code>git config user.name</code> 查看某一项配置 <code>git config --list --show-origin</code> 查看所有的配置以及它们所在的文件 
|-
|设置用户信息
|配置全局用户名称和邮箱，<syntaxhighlight lang="bash" >
git config --global user.name "Your Name"
git config --global user.email yourname@example.com
</syntaxhighlight>
如果某个项目想要使用不同的用户名称与邮件地址时，在项目目录，使用不带<code>--global</code>设置用户信息。
|}
{{了解更多
|[https://git-scm.com/book/zh/v2/附录-C:-Git-命令-设置与配置《Pro Git》中文版V2：附录 C: Git 命令 - 设置与配置]
}}

===创建仓库===
{| class="wikitable"
|-
! 命令
! 描述
! 示例
|-
| git init
| 初始化一个Git仓库
| <code>git init myproject</code>
|-
| git clone
| 克隆一个Git仓库到本地
| <nowiki>git clone https://github.com/git/git.git</nowiki>
|-
|}

===快照===
{| class="wikitable"
|-
! 命令
! 描述
! 示例
|-
| git add
| 添加文件到暂存区
| <code>git add README.md</code> <code>git add .</code>
|-
| git commit
| 提交更新到本地仓库
| <code>git commit -m "Update README"</code>
|-
| git status
| 查看文件状态
| git status
|-
| git diff
| 比较工作区和暂存区差异
| git diff
|-
| [https://git-scm.com/docs/git-reset/zh_HANS-CN git reset]
| 重置当前HEAD到指定状态。可以使用<code>git log --oneline</code>或<code>git reflog</code>查看要回滚的版本。 参数： <code>--soft</code>：本地仓库回滚，但是暂存区和工作区保持不变。 <code>--mixed</code>：本地仓和暂存区回滚，默认参数，等同于git reset。 <code>--hard</code>：本地仓、暂存区和工作区都回滚。注意，如果工作区有没有提交的代码就找不回。
|<code>git reset --soft HEAD~1</code> <code>git reset HEAD~1</code> <code>git reset --hard HEAD~1</code> <code>git reset --hard cba9527</code>
|-
| git rm
| 从暂存区和工作区删除文件
| git rm README.md
|-
| git mv
| 移动或重命名文件、目录
| git mv file.txt file2.txt
|-
| [https://git-scm.com/docs/git-clean/zh_HANS-CN git clean]
| 删除工作区未跟踪文件。 常用参数： <code>-d</code> <code>-f</code>直接删除。 <code>-i</code>交互模式，显示会做什么，并以交互方式清理文件。
| <code>git clean -i</code> <code>git clean -di</code> <code>git clean -df</code>
|}
{{了解更多
|[https://git-scm.com/book/zh/v2/附录-C:-Git-命令-快照基础《Pro Git》中文版V2：附录 C: Git 命令 - 快照基础]
}}

===分支管理===
{| class="wikitable"
|-
! 命令
! 描述
! 示例
|-
| git branch
| 列出/创建/删除分支
|<code>git branch</code>列出所有分支 <code>git branch -v</code> <code>git branch dev</code>创建名称为dev分支
|-
| git checkout
| 切换分支，或者检出内容到工作目录。
| <code>git checkout dev</code>切换到dev分支 <code>git checkout -b main</code> 创建一个新的 main 分支并立即切换到该分支。 <syntaxhighlight lang="bash" >
git checkout -b main
git push origin main
git branch -d master
</syntaxhighlight> 将master分支重命名为main分支。1.创建 main 分支。2.main 分支推送到远程存储库，并覆盖旧的 master 分支。3.删除旧的 master 分支
|-
| git log
| 查看提交历史记录
|<code>git log</code> <code>git log --oneline</code>
|-
| git tag
| 打标签，创建、列出、删除标签。
| <code>git tag</code>列出标签 <code>git tag -l "v2.3.5*"</code>列出v2.3.5开头标签
|-
| git merge
| 合并一个或者多个分支
|
|-
| git mergetool
| 解决合并冲突
|
|-
| git stash
| 暂存当前工作目录状态
|
|}
{{了解更多
|[https://git-scm.com/book/zh/v2/附录-C:-Git-命令-分支与合并《Pro Git》中文版V2：附录 C: Git 命令 - 分支与合并]
}}

===远程===
{| class="wikitable"
|-
! 命令
! 描述
! 示例
|-
|git clone
|克隆远程仓库
|
|-
|git remote -v
|查看远程仓库列表。用于查看当前仓库已经配置的远程仓库列表，以及它们的URL。
|<code>git remote -v</code>
|-
|git remote show <远程仓库名>
|查看特定远程仓库的详细信息。默认情况下，有一个 origin 的远程仓库名，它是 Git 的默认远程仓库名称。多个远程仓库时，可以使用不同的名称来管理。
| <code>git remote show origin</code> 显示origin远程仓库的信息，包括远程仓库地址，分支等信息。
|-
| git remote add <远程仓库名> <URL>
|
|
|-
| git fetch <远程仓库名>
| 获取远程代码
|
|-
|git pull <远程仓库名> <分支名>
| 拉取远程代码及立即合并，相当于git fetch后执行git mergin。
| <code>git pull origin main</code> 从远程的"origin"仓库的"main"分支中拉取最新的更改并将其合并到你的本地分支中。
|-
| git push <远程仓库名> <本地分支名>:<远程分支名>
|推送本地更改
| <code>git push origin main</code> 将本地当前分支推送到远程origin仓库的main分支。 <code>git push origin --delete test</code>删除远程名称为test的分支，注意先备份数据。
|-
|
|
|
|-
|
|
|
|}

==SSH + 裸仓库==
=== 服务端配置 ===
以局域网建立建立git仓库示例，外网使用还需要更多安全设置，如改端口、密钥认证、fail2ban，git-shell 限制等。
以ubuntu示例：
<syntaxhighlight lang="bash">
# 安装git，已安装跳过
sudo apt update && sudo apt install git -y

# 创建一个专门用于 Git 服务的系统用户
sudo useradd -m -s /bin/bash git
# 设置密码（可选）
sudo passwd git

# 可选配置 git-shell 限制
# 限制 git 用户只能执行 git 相关命令，不能登录 shell
sudo chsh git -s $(which git-shell)

# 切换到git用户
sudo su - git
# 初始化裸仓库
git init --bare project.git
# 可选：设置默认分支为 main
git config --global init.defaultBranch main
</syntaxhighlight>

=== 客户端使用 ===
假设服务器ip为192.168.1.100，配置[[SSH]]密钥，就不用输入密码。
<syntaxhighlight lang="bash">
# 克隆仓库
git clone git@192.168.1.100:project.git

# 推送本地已有项目
git remote add origin git@192.168.1.100:project.git
git push -u origin main

# 日常协作命令
git pull origin main # 拉取更新
git push origin main # 推送更新
</syntaxhighlight>

==Hooks 钩子==
Git 钩子（Hooks ）用于在特定的重要动作发生时触发自定义脚本。分为客户端的和服务器端的。

{{了解更多
|[https://git-scm.com/book/zh/v2/%E8%87%AA%E5%AE%9A%E4%B9%89-Git-Git-%E9%92%A9%E5%AD%90 中文版V2：8.3 自定义 Git - Git 钩子 ]
}}
===快速入门===
钩子默认位于Git目录下<code>.git/hooks</code>目录中，文件名为钩子名称(没有扩展名)，如<code>pre-commit</code>，该文件将在commit前运行。初始化git项目时，hooks目录下有很多示例脚本，都是以<code>.sample</code>结尾，如果要启用去掉这个后缀。

以下示例使用<code>post-commit</code>钩子在每次提交时将最新的 commit ID 写入一个 version.txt 文件。
*创建钩子：<code>touch .git/hooks/post-commit</code>。
*编辑钩子：
<syntaxhighlight lang="bash" >
#!/bin/sh

# 获取最新的短 commit ID
COMMIT_ID=$(git rev-parse --short HEAD)

# 将 commit ID 写入临时文件
echo $COMMIT_ID > version.txt.tmp

# 如果 version.txt 不存在或内容不同于临时文件，才更新 version.txt
if [ ! -f version.txt ] || ! cmp -s version.txt.tmp version.txt; then
mv version.txt.tmp version.txt
git add version.txt
git commit --amend --no-edit --allow-empty
else
rm version.txt.tmp
fi
</syntaxhighlight>
* 使 post-commit 钩子可执行：<code>chmod +x .git/hooks/post-commit</code>
{{了解更多
|[https://git-scm.com/book/zh/v2/%E8%87%AA%E5%AE%9A%E4%B9%89-Git-Git-%E9%92%A9%E5%AD%90 中文版V2：8.3 自定义 Git - Git 钩子 ]
}}

==设置==
=== Linux终端显示当前Git分支 ===
进入用户的Home目录，编辑.bashrc文件
<syntaxhighlight lang="bash">
cd ~
vim .bashrc
</syntaxhighlight>
将下面代码加入.bashrc文件末尾，并保存：
<syntaxhighlight lang="bash">
function git_branch {
branch="`git branch 2>/dev/null | grep "^\*" | sed -e "s/^\*\ //"`"
if [ "${branch}" != "" ];then
if [ "${branch}" = "(no branch)" ];then
branch="(`git rev-parse --short HEAD`...)"
fi
echo " ($branch)"
fi
}
export PS1='\u@\h \[\033[01;36m\]\W\[\033[01;32m\]$(git_branch)\[\033[00m\] \$ '
</syntaxhighlight>
保存并退出，执行加载命令
<syntaxhighlight lang="bash">
source ./.bashrc
</syntaxhighlight>

==资源==
===官网===
*Git 官网：https://git-scm.com/
*Git 文档：https://git-scm.com/doc
* Git 文档参考 https://git-scm.com/docs
*Git 文档：书籍《Pro Git》中文版：https://git-scm.com/book/zh/v2

===文章===
*[https://zh.wikipedia.org/wiki/Git 维基百科：git]

[[分类:编程工具]]

Piper TTS

2026-04-20T01:46:07Z

Eric：/* 中文 */

Piper TTS是一个快速、本地运行的神经网络文本转语音（TTS）引擎，基于 VITS 模型，使用 ONNX 格式运行。它支持多种语言（包括中文），模型体积小、速度快，即使在低端硬件（如 Raspberry Pi）上也能实时合成高质量、自然的语音，完全离线隐私安全。注意：原 rhasspy/piper 仓库已归档，开发迁移到 OHF-Voice/piper1-gpl（GPL 许可）。

==简介==
===时间轴===

==安装==

==快速入门==

==中文==
对于离线，可以先在Hugging Face下载需要的模型和安装需要的包：
*piper-voices中文模型： https://huggingface.co/rhasspy/piper-voices/tree/main/zh/zh_CN
*g2pW模型：默认路径download_dir / "g2pW"，其中 download_dir 默认是当前工作目录（即你运行 Python 脚本或 piper 命令时的目录）。
*bert-base-chinese模型：G2PWConverter 在初始化时调用了 BertTokenizer.from_pretrained(self.model_source)，而 model_source 默认是 "bert-base-chinese"。地址：https://huggingface.co/google-bert/bert-base-chinese/tree/main。
*Sentence Stream包：安装 <code>pip install sentence-stream</code>。这个模块是 OHF-Voice 自己维护的一个小型句子分割器（sentence splitter），专门用于把长文本按句子切分后再做 phonemization。

文件结构如下：
<syntaxhighlight lang="python" >
/path/to/project/
├── voices/
│ ├── zh_CN-chaowen-medium.onnx
│ ├── zh_CN-chaowen-medium.onnx.json
└── ... （其他模型）
├── g2pW/
│ ├── g2pw.onnx
│ ├── config.json
│ └── ...
├── bert-base-chinese/
│ ├── config.json
│ ├── tokenizer_config.json
│ ├── vocab.txt
│ ├── pytorch_model.bin （或 model.safetensors）
│ ├── tokenizer.json
│ └── ... （其他必要文件）
└── test.py
</syntaxhighlight>

简单测试test.py：
<syntaxhighlight lang="python" >
import os
import wave
from pathlib import Path
import piper

# 完全离线设置（防止任何网络尝试）
os.environ["TRANSFORMERS_OFFLINE"] = "1"
os.environ["HF_HUB_OFFLINE"] = "1"

model_path = Path("/path/to/project/voices/zh_CN-chaowen-medium.onnx")
download_dir = Path("/path/to/project/")

voice = piper.PiperVoice.load(model_path=model_path, download_dir=download_dir)

# 运行一次自定义 phonemizer，指定bert-base-chinese位置。
from piper.phonemize_chinese import ChinesePhonemizer
from g2pw import G2PWConverter

class OfflineChinesePhonemizer(ChinesePhonemizer):
def __init__(self, model_dir: Path):
super().__init__(model_dir) # 先让它找到 g2pw.onnx
# 重新初始化 g2p，使用本地 bert-base-chinese
bert_path = download_dir / "bert-base-chinese"
self.g2p = G2PWConverter(
model_dir=str(model_dir),
model_source=str(bert_path), # 本地 bert 路径
style="pinyin",
enable_non_tradional_chinese=True
)

# 替换 phonemizer
voice._chinese_phonemizer = OfflineChinesePhonemizer(download_dir / "g2pW")

# 合成语音
out_file = "test.wav"
text = "你好，树莓派。"
print("正在合成:", text)

with wave.open(out_file, "wb") as wav_file:
voice.synthesize_wav(text, wav_file)

print(f"✅ 成功生成 test.wav, 地址：{Path(out_file).resolve()}")
</syntaxhighlight>

==资源==
===官网===

===网站===

===文章===
* https://calbryant.uk/blog/training-a-new-ai-voice-for-piper-tts-with-only-4-words

Piper TTS

2026-04-19T16:46:38Z

Eric：

Piper TTS是一个快速、本地运行的神经网络文本转语音（TTS）引擎，基于 VITS 模型，使用 ONNX 格式运行。它支持多种语言（包括中文），模型体积小、速度快，即使在低端硬件（如 Raspberry Pi）上也能实时合成高质量、自然的语音，完全离线隐私安全。注意：原 rhasspy/piper 仓库已归档，开发迁移到 OHF-Voice/piper1-gpl（GPL 许可）。

==简介==
===时间轴===

==安装==

==快速入门==

==中文==
对于离线，可以先在Hugging Face下载需要的模型和安装需要的包：
*piper-voices中文模型： https://huggingface.co/rhasspy/piper-voices/tree/main/zh/zh_CN
*g2pW模型：默认路径download_dir / "g2pW"，其中 download_dir 默认是当前工作目录（即你运行 Python 脚本或 piper 命令时的目录）。
*bert-base-chinese模型：G2PWConverter 在初始化时调用了 BertTokenizer.from_pretrained(self.model_source)，而 model_source 默认是 "bert-base-chinese"。地址：https://huggingface.co/google-bert/bert-base-chinese/tree/main。
*Sentence Stream包：安装 <code>pip install sentence-stream</code>。这个模块是 OHF-Voice 自己维护的一个小型句子分割器（sentence splitter），专门用于把长文本按句子切分后再做 phonemization。

文件结构如下：
<syntaxhighlight lang="python" >
/path/to/project/
├── voices/
│ ├── zh_CN-chaowen-medium.onnx
│ ├── zh_CN-chaowen-medium.onnx.json
└── ... （其他模型）
├── g2pW/
│ ├── g2pw.onnx
│ ├── config.json
│ └── ...
├── bert-base-chinese/
│ ├── config.json
│ ├── tokenizer_config.json
│ ├── vocab.txt
│ ├── pytorch_model.bin （或 model.safetensors）
│ ├── tokenizer.json
│ └── ... （其他必要文件）
└── test.py
</syntaxhighlight>

简单测试test.py：
<syntaxhighlight lang="python" >
import wave
from piper import PiperVoice

# 相对路径或绝对路径
model_path = "/path/to/project/voices/zh_CN-chaowen-medium.onnx"
download_dir = "/path/to/project/"

# 加载语音
voice = PiperVoice.load(model_path, download_dir=download_dir)

with wave.open("test.wav", "wb") as wav_file:
voice.synthesize_wav("你好，树莓派。", wav_file)
</syntaxhighlight>

==资源==
===官网===

===网站===

===文章===
* https://calbryant.uk/blog/training-a-new-ai-voice-for-piper-tts-with-only-4-words

Piper TTS

2026-04-19T16:14:51Z

Eric：创建页面，内容为“Piper TTS是一个快速、本地运行的神经网络文本转语音（TTS）引擎，基于 VITS 模型，使用 ONNX 格式运行。它支持多种语言（包括中文），模型体积小、速度快，即使在低端硬件（如 Raspberry Pi）上也能实时合成高质量、自然的语音，完全离线隐私安全。注意：原 rhasspy/piper 仓库已归档，开发迁移到 OHF-Voice/piper1-gpl（GPL 许可）。 ==简介== ===时间轴=== ==安…”

Piper TTS是一个快速、本地运行的神经网络文本转语音（TTS）引擎，基于 VITS 模型，使用 ONNX 格式运行。它支持多种语言（包括中文），模型体积小、速度快，即使在低端硬件（如 Raspberry Pi）上也能实时合成高质量、自然的语音，完全离线隐私安全。注意：原 rhasspy/piper 仓库已归档，开发迁移到 OHF-Voice/piper1-gpl（GPL 许可）。

==简介==
===时间轴===

==安装==

==快速入门==

==资源==
===官网===

===网站===

===文章===
* https://calbryant.uk/blog/training-a-new-ai-voice-for-piper-tts-with-only-4-words

CosyVoice

2026-04-19T03:00:40Z

Eric：创建页面，内容为“CosyVoice是一款开源的文本转语音（TTS）系统。支持多语言，中文支持18种方言口音。 ==简介== ===时间轴=== ==快速入门== ==资源== ===官网=== * https://github.com/FunAudioLLM/CosyVoice * https://funaudiollm.github.io/cosyvoice3 ===网站===”

CosyVoice是一款开源的文本转语音（TTS）系统。支持多语言，中文支持18种方言口音。

==简介==
===时间轴===

==快速入门==

==资源==
===官网===
* https://github.com/FunAudioLLM/CosyVoice
* https://funaudiollm.github.io/cosyvoice3

===网站===

Docker

2026-04-18T15:45:15Z

Eric：/* 常用仓库 */

Docker 是一个开源软件的容器引擎软件。

==简介==
===时间轴===
* 2013年3月13日，发布初始版本。

===虚拟机与容器===
[[虚拟机]]可以在一种操作系统里面运行另一种操作系统，但虚拟机，资源占用多，启动慢。

容器是操作系统层虚拟化，容器化的优势在于占用服务器空间少，通常几秒内即可引导。

Docker 是一种容器的管理方式。下文的容器主要指Docker的容器。

===安装===
====CentOS====
官网建议安装在[[CentOS]] 7及以上的系统。如果之前有安装docker，先卸载之前版本。三种安装方法：
*添加Docker源进行安装，安装和升级方便，这是推荐的方法。
*下载RPM软件包，手动安装。
*官方一键安装脚本，一些测试和开发用户会选择这种方法。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#安装所需的软件包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

#安装containerd.io软件包，不然会报错requires containerd.io >= 1.2.2-3
sudo yum install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm

#设置官网的稳定版仓库源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

#可选，体验版和测试版默认是关闭的，可以通过命令打开，详细见文档。

#安装最新版本的docker CE
sudo yum install docker-ce

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

也可以使用dnf命令安装，dnf为下一代yum命令。
<syntaxhighlight lang="bash">
sudo dnf -y install dnf-plugins-core
sudo dnf install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce
sudo systemctl start docker
</syntaxhighlight>

方法二，下载RPM包，离线安装：
<syntaxhighlight lang="bash">
#在联网的计算机下载RPM软件包，从官网地址选一个版本下载：https://download.docker.com/linux/fedora/
#比如：docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#复制到计算机的某个目录，执行安装
sudo dnf -y install docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

方法三，使用脚本安装：
Docker提供脚本安装方式，快捷安装。
<syntaxhighlight lang="bash">
#下载脚本
curl -fsSL https://get.docker.com -o get-docker.sh
#运行脚本安装
sudo sh get-docker.sh

#如果以非root用户使用docker（推荐），需要添加一个用户到'docker'用户组中
#查看是否添加成功，如果添加当前登录的用户，需要重新登录，组权限才会生效。
sudo usermod -aG docker your-user-name

#查看是否安装成功
docker --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/engine/install/centos/ Docker文档-centos安装Docker引擎]
}}

====Ubuntu====
[[Ubuntu]]安装Docker也有三种方法，与[[CentOS]]安装docker类似。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#获取apt可用最新列表
sudo apt-get update
#使用apt安装下列软件包
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg-agent \
software-properties-common
#添加docker官方GPG密钥，验证密钥指纹9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
#添加docker的稳定源
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"

#获取apt可用最新列表
sudo apt-get update
#安装最新版的Docker CE
sudo apt-get install docker-ce docker-ce-cli containerd.io

#检验是否安装成功
sudo docker run hello-world
#使用非root用户使用docker，可以将用户添加到docker组：
sudo gpasswd -a ${USER} docker #将当前用户添加到docker组，重新登录后生效
sudo usermod -aG docker your-user #将其他用户添加到docker组
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/install/linux/docker-ce/ubuntu/ Docker文档-Ubuntu安装Docker CE]
}}

==快速入门==

==镜像==
镜像(Image)是只读文件，容器是运行在镜像之上，运行容器时会复制镜像然后启动。镜像的一些属性：
*REPOSITORY：表示镜像的仓库源
*TAG：镜像的标签
*IMAGE ID：镜像ID
*CREATED：镜像创建时间
*SIZE：镜像大小

当运行容器时，使用的镜像如果在本地中不存在，docker 就会自动从 docker 镜像仓库中下载，默认是从 Docker Hub 公共镜像源下载。

===镜像使用===
可以命令行输入<code>命令 --help</code>查看帮助，如在命令行输入<code>docker search --help</code>
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/image_ls/ docker image ls] [https://docs.docker.com/engine/reference/commandline/images/ docker images]
| '''查看镜像''' 列出本地主机上的镜像
| <code>docker image ls</code>查看本地镜像 <code>docker images -a </code>列出本地主机上的镜像，包括默认隐藏的中间镜像。
|-
| [https://docs.docker.com/engine/reference/commandline/tag/ docker tag] docker image tag
| '''创建引用标签''' 为镜像创建新标签，方便使用。
| <code>docker tag 0e1234567893 ubuntu:V20</code>为ID：0e1234567893的镜像加多个标签ubuntu:V20 <code>docker tag ubuntu:18.04 mytest/ubuntu:18</code>为ubuntu:18.04镜像添加标签mytest/ubuntu:18
|-
| docker image rm docker rmi
| '''删除镜像''' 删除镜像正在使用的镜像会报错
| <code>docker image rm Ubuntu</code> <code>docker rmi Ubuntu</code>
|-
| docker image prune
| '''清理镜像''' 删除未使用的镜像
| <code>docker image prune</code>删除未使用的镜像
|-
| [https://docs.docker.com/engine/reference/commandline/image_pull/ docker pull]
| '''下载镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上下载。
| <code>docker pull ubuntu</code>默认下载tag: latest的版本 <code>docker pull ubuntu:18.04</code>指定镜像版本
|-
| docker search
| '''搜索镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上搜索。 输出结果说明： NAME: 镜像仓库源的名称 DESCRIPTION: 镜像的描述 OFFICIAL: 是否docker官方发布 START: 表示点赞数量 AUTOMATED: 自动构建
| <code>docker search nginx</code>搜索nginx软件的镜像 <code>docker search --filter=is-offical=true mysql</code>搜索mysql软件的镜像 <code>docker search --filter=stars=100 mysql</code>搜索star超过100的mysql镜像
|-
|docker push
|'''上传镜像''' 默认上传到Docker镜像仓库[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。先注册一个免费Docker 账号，接下来可以在终端操作。
|<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
|-
| docker history
| '''镜像历史''' 查看制作镜像的命令 格式：<code>docker history [参数] 镜像</code>
|<code>docker history nginx</code>查看nginx镜像制作的历史
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/image/ Docker 参考：docker image]
|[https://docs.docker.com/engine/reference/commandline/images/ Docker 参考：docker images]
}}

===常用镜像===
====操作系统基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| busybox
|
|
|
|-
| alpine
| 5 MB
| Alpine Linux是一个面向安全的轻型的Linux发行版。Alpine不包含 bash 因此进入某个alpine docker容器，可以使用sh命令，如： <code>docker exec -it container_name sh</code>进入某个容器并运行sh。 <code>docker run -it -v data_volume:/data alpine:3.16.9 sh</code>启动一个容器，挂在data_volume卷到容器的/data目录。
| 官网：https://www.alpinelinux.org/ 镜像：https://hub.docker.com/_/alpine/
|-
| ubuntu
| 30 MB
|
|官网：http://www.ubuntu.com/ 镜像：https://hub.docker.com/_/ubuntu/
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

====编程语言基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| python
| 50 MB 350 MB 2.64G
|
| 镜像： https://hub.docker.com/_/python/
|-
| node
|
| Node.js是一个基于JavaScript的平台，用于服务器端和网络应用程序。
| 镜像：https://hub.docker.com/_/node/
|-
|
|
|
|
|-
|
|
|
|
|}

===制作镜像===
当docker镜像仓库没有想要的镜像，可以通过以下两种方式制作镜像。
*在已有容器中修改，再提交保存为新镜像。
*使用Dockerfile文件，从头创建一个新的镜像。

====容器打包为镜像====
修改容器，通过命令 docker commit 将容器打包为新镜像。如：
<syntaxhighlight lang="bash">
#启动一个名称ubuntu-18为容器，并进入容器终端
docker run --name ubuntu-18 -it ubuntu:18.04 /bin/bash

#在容器内修改，如更新软件，
apt-get update

#退出这个容器
exit

#提交打包镜像
docker commit ubuntu-18 ubuntu-updated
</syntaxhighlight>

====Dockerfile创建镜像====
Docker可以自动读取Dockerfile文件里的指令生成一个镜像。Dockerfile是一个文本文件，都是一些关于组装镜像的指令。通过docker build命令来生成一个镜像。

====Dockerfile语法====
Dockerfile文件格式如下：
# Comment 注释
INSTRUCTION arguments

注释使用#号，指令不区分大小写，但一般指令使用大写，这样容易和后面参数区分开来。

====Dockerfile指令====
{| class="wikitable" style="width: 100%;
!指令!!格式!!描述!!示例
|-
|[https://docs.docker.com/engine/reference/builder/#from FROM]
|FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
|初始化，设置基准镜像。这个指令必须放开头。
|FROM debian:buster-slim
|-
|[https://docs.docker.com/engine/reference/builder/#run RUN]
|RUN <command> 或 RUN ["executable", "param1", "param2"]
|执行命令
|RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'
|-
|[https://docs.docker.com/engine/reference/builder/#cmd CMD]
|CMD ["param1","param2"] CMD command param1 param2 CMD ["executable","param1","param2"]
|容器启动时执行的命令。该指令只能有一个，当有多个RUN指令只会执行最后一个
|
|-
|[https://docs.docker.com/engine/reference/builder/#label LABEL]
|LABEL <key>=<value> <key>=<value> <key>=<value> ...
|给镜像添加元数据。如添加一些作者信息，版本信息等。可以使用docker image inspect命令查看镜像所有信息，包括标签。
|LABEL maintainer="yourname@domain.com" version="1.0"
|-
|[https://docs.docker.com/engine/reference/builder/#expose EXPOSE]
|EXPOSE <port> [<port>/<protocol>...]
|开放容器某个端口，默认协议为TCP。运行主机可以通过docker run命令增加-p参数来对接这个端口。
|EXPOSE 80/udp
|-
|[https://docs.docker.com/engine/reference/builder/#env ENV]
|ENV <key> <value> ENV <key>=<value> ...
|设置环境变量
|ENV myName John Doe
|-
|[https://docs.docker.com/engine/reference/builder/#add ADD]
|ADD [--chown=<user>:<group>] <src>... <dest> ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件、目录或URLs到镜像中。src的路径支持Go语言的filepath.Match规则。
|ADD test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#copy COPY]
|COPY [--chown=<user>:<group>] <src>... <dest> COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件或目录到镜像中。src的路径支持Go语言的filepath.Match规则。
|COPY test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#entrypoint ENTRYPOINT]
|ENTRYPOINT ["executable", "param1", "param2"] ENTRYPOINT command param1 param2
|容器启动时执行的命令。
|ENTRYPOINT ["top", "-b"]
|-
|[https://docs.docker.com/engine/reference/builder/#volume VOLUME]
|VOLUME ["/data"]
|创建挂载点
|VOLUME /myvol
|-
|[https://docs.docker.com/engine/reference/builder/#user USER]
|USER <user>[:<group>] USER <UID>[:<GID>]
|设置启动容器的用户，可以是用户名或UID。
|USER username
|-
|[https://docs.docker.com/engine/reference/builder/#workdir WORKDIR]
|WORKDIR /path/to/workdir
|设置工作目录，对RUN, CMD, ENTRYPOINT, COPY 和 ADD指令有效。
|WORKDIR /home/foo/work
|-
|[https://docs.docker.com/engine/reference/builder/#arg ARG]
|ARG <name>[=<default value>]
|设置构建镜像时变量，构建docker build时使用--build-arg <varname>=<value>传递变量值。
|ARG user1=someuser
|-
|[https://docs.docker.com/engine/reference/builder/#onbuild ONBUILD]
|ONBUILD <INSTRUCTION>
|设置触发指令，当该镜像作为基准镜像，构建时执行。
|
|-
|[https://docs.docker.com/engine/reference/builder/#stopsignal STOPSIGNAL]
|STOPSIGNAL signal
|
|
|-
|[https://docs.docker.com/engine/reference/builder/#healthcheck HEALTHCHECK]
|HEALTHCHECK [OPTIONS] CMD command HEALTHCHECK NONE
|告诉dockers该镜像的容器正常工作状况
|<nowiki>HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost/ || exit 1 </nowiki>
|-
|[https://docs.docker.com/engine/reference/builder/#shell SHELL]
|
|
|
|-
|}

====docker build构建镜像====

{{了解更多
| [https://docs.docker.com/engine/reference/builder/ Docker参考：Dockerfile]
}}

== 容器 ==
容器（Container）是运行在镜像之上，运行容器时会复制镜像然后启动。
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/run/ docker run]
| '''运行容器''' docker run [参数] 镜像 [COMMAND] [ARG...] 从镜像启动一个新容器。该命令会检查本地是否有镜像，没有就从docker仓库中下载。 常用参数： <code>--name</code> 容器命名，如<code>--name test</code> <code>--restart</code> 重启策略，如停止后自动重启：<code>--restart=always</code> <code>-P</code> 绑定端口 <code>-v</code> 挂载
| <code>docker run -it ubuntu</code>使用 ubuntu 镜像启动一个容器 <code>docker run -it ubuntu /bin/bash</code>启动一个ubuntu容器，并进入终端。要退出容器里的终端输入exit。<code>docker run -itd --name ubuntu-test ubuntu /bin/bash</code>启动一个名称ubuntu-test为容器，并后台运行。参数-d表示后台运行。
|-
| [https://docs.docker.com/engine/reference/commandline/update/ docker update]
| '''更新容器''' 动态更新容器配置。 常用参数： <code>--memory</code> , <code>-m</code> 内存限制 <code>--restart</code> 重启策略
| <code>docker update --restart=unless-stopped mynginx</code> 配置mynginx容器重启策略为unless-stopped
|-
| docker start
| '''启动容器''' 启动已经停止的容器。
| <code>docker start dw3342531d3</code> 启动一个容器id为dw3342531d3的容器。
|-
| docker restart
|'''重启容器''' 重启正在运行的容器。
| <code>docker restart ubuntu-test</code> 重启容器ubuntu-test。
|-
| [https://docs.docker.com/engine/reference/commandline/ps/ docker ps]
|'''查看本地容器列表''' 重启正在运行的容器。 常用参数： <code>--no-trunc</code> 显示完整内容，不截断。
|<code>docker ps</code>查看正在运行的容器 <code>docker ps -a</code>查看所用容器，包括停止的 <code>docker ps --no-trunc</code>
|-
|[https://docs.docker.com/engine/reference/commandline/inspect/ docker inspect]
|'''查看容器信息''' 查看容器底层信息。它会返回一个 JSON 文件记录着 Docker 容器的配置和状态信息。 常用参数： <code>-f, --format </code> 使用Go语言template格式化输出。
|<code>docker inspect ubuntu-test</code> 查看ubuntu-test容器信息 <code><nowiki>docker inspect --format='{{.NetworkSettings.IPAddress}}' test2</nowiki></code> 查看test2容器ip <code><nowiki>docker inspect -f '{{.Name}} - {{range .NetworkSettings.Networks }} {{.IPAddress}} {{end}}' $(docker ps -aq)</nowiki></code> 查看所有容器ip地址。 <code><nowiki>docker inspect -f '{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' test2</nowiki></code> 查看test2容器MAC <code><nowiki>docker inspect --format='{{.LogPath}}' test2</nowiki></code> 查看test2容器的log地址 <code><nowiki>docker inspect -f '{{.Config.Image}}' test2</nowiki></code> 查看test2容器的镜像名称
|-
|[https://docs.docker.com/engine/reference/commandline/stats/ docker stats]
|'''实时统计容器使用资源''' 统计容器使用主机CUP、内存的百分比，通过网络发送和接收的数据量，从主机上的块设备读取和写入的数据量。
|<code>docker stats</code>
|-
|[https://docs.docker.com/engine/reference/commandline/logs/ docker logs]
|'''查看容器日志''' 查看容器内部的标准输出。
|<code>docker logs ubuntu-test</code>查看ubuntu-test容器内部的标准输出 <code>docker logs -f ubuntu-test</code>跟踪日志输出
|-
| docker top
|'''查看容器进程''' 查看容器内部运行的进程
| <code>docker top static_web</code> 查看static_web容器内部运行的进程
|-
| [https://docs.docker.com/engine/reference/commandline/exec/ docker exec]
|'''运行命令''' 在容器中运行命令。该命令退出容器终端，容器不会停止。
|<code>docker exec ubuntu-test ls</code>在ubuntu-test容器工作目录运行ls命令 <code>docker exec -it ubuntu-test bash</code>进入ubuntu-test容器交互式终端 <code>docker exec -u 0 -it test bash</code>以root用户进入名称为test的容器
|-
| docker attach
|'''附着终端''' 将本地终端标准输入、输出和错误流连接到运行的容器中。该命令退出容器终端，容器会停止，推荐使用<code>docker exec -it</code>。
|<code>docker attach ubuntu-test</code>
|-
|docker stop
|'''停止容器''' 停止运行中的容器
|<code>docker stop dw3342531d3</code> #停止一个id为dw3342531d3的容器 <code>docker stop $(docker ps -a -q)</code>停止所有运行中的容器
|-
|docker rm
|'''删除容器''' 删除容器，需要容器停止运行。参数-f表示强制删除，可以不用等容器停止后再删除。
|<code>docker rm ubuntu-test</code>删除ubuntu-test容器 <code>docker rm -f ubuntu-test</code>强制删除ubuntu-test容器 <code>docker rm -f $(docker ps -a -q)</code>'''注意，该命令会强制删除所有容器'''
|-
|docker container prune
|'''清理容器''' 删除所有停止的容器。
|<code>docker container prune</code>删除所有停止的容器。
|-
|docker commit
|'''容器构建镜像''' 将容器打包为一个镜像。
|<code>docker commit ubuntu-test ubuntu-updated</code>#将ubuntu-test容器打包为一个名称为ubuntu-updated镜像。
|}

== 仓库 ==
仓库（Repository）是集中存放镜像的地方。 Docker的官方镜像仓库为[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。

===Docker Hub===
大部分需求都可以通过在Docker Hub中直接下载镜像来实现。在[https://hub.docker.com https://hub.docker.com]免费注册一个 Docker 账号。接下来可以在终端操作
<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#在Docker Hub仓库中搜索使用docker search，这命令可以不登录。
docker search ubuntu

#下载镜像使用docker pull，这命令可以不登录。
docker pull ubuntu

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
可能出现问题：
*登录时出现：Error saving credentials: error storing credentials - err: exit status 1, out: `Cannot autolaunch D-Bus without X11 $DISPLAY`
执行下面命令即可：sudo apt install gnupg2 pass

*docker push报错：denied: requested access to the resource is denied
镜像名和用户名不匹配，使用tag将镜像名改为username/镜像名，username为个人的用户名，然后再推送，如：
docker tag ubuntu:18.04 username/ubuntu:18.04
docker push username/ubuntu:18.04

===其他公有镜像仓库===
==== 常用仓库 ====
{| class="wikitable" style="width: 100%;
! 提供方
! 仓库地址
! 描述
! 网址
|-
| 毫秒镜像
| https://docker.1ms.run
| 免费不需要登录，速度慢。付费12个月10元50G。
|https://1ms.run/
|-
| 阿里云
| https://xxxxxxxx.mirror.aliyuncs.com
| 需要注册阿里云，在镜像加速器可以看到仓库地址。
| [https://cr.console.aliyun.com/ 官网] [https://developer.aliyun.com/article/110806 文档]
|-
| 网易
| https://hub.c.163.com
|
| [https://sf.163.com/help/documents/56918246390157312 文档]
|-
| 百度云
| https://mirror.baidubce.com
|
|[https://cloud.baidu.com/doc/CCE/s/Yjxppt74z#如何使用dockerhub镜像加速器文档]
|-
| Google
|
|
|[https://cloud.google.com/container-registry/docs/pulling-cached-images 文档]
|}

==== 使用方法 ====
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| 拉取时指定仓库
| 单次有效 仓库地址不包含协议(如<code>https://</code>)，公有镜像仓库一般使用<code>library</code>。 如指定阿里镜像仓库拉取ubuntu： <code>docker pull xxxxxxxx.mirror.aliyuncs.com/library/ubuntu</code>
|-
| 编辑配置文件
| 永久有效 步骤： 1.编辑配置文件，<code>sudo vim /etc/docker/daemon.json</code>，输入如下内容<syntaxhighlight lang="json">
{
"registry-mirrors": [
"https://hub-mirror.c.163.com"
]
}
</syntaxhighlight>
2.重启docker服务，<code>sudo service docker restart</code> 3.查看是否成功，<code>docker info</code> 输出含有Registry Mirrors
|-
|
|
|}

===搭建私有镜像仓库===
<syntaxhighlight lang="bash" >
# 运行一个本地仓库
docker run -d -p 5000:5000 --restart always --name registry registry:3

# 现在，在Docker里使用，如推送，拉取
docker pull ubuntu
docker tag ubuntu localhost:5000/ubuntu
docker push localhost:5000/ubuntu
</syntaxhighlight>

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/
===镜像dockehub镜像仓库===
使用 Docker 启动 Registry 镜像加速服务
<syntaxhighlight lang="bash" >
sudo docker run -d \
--name dockerhub \
--restart=always \
-p 443:5000 \
-v /data/docker-registry:/var/lib/registry \
-v /your/domain/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.cer \
-e REGISTRY_HTTP_TLS_KEY=/certs/docker.yourdomain.com.key \
-e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
registry:3
</syntaxhighlight>

在其他电脑测试拉取镜像：
sudo docker pull yourdomain.com/library/hello-world

成功拉取后，可以配置 Docker 的默认镜像地址方便使用，没有成功查看运行日志<code>sudo docker logs dockerhub</code>。

进阶版本，使用registry + Nginx + HTTPS进行镜像加速。

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/

==网络==
===概览===
Docker的网络是可拔插的子系统，使用驱动程序。docker内置了几个驱动程序，提供了核心网络功能。
{| class="wikitable" style="width: 100%;
! 网络模式
! 描述
! 示例
|-
| 桥接模式 [https://docs.docker.com/network/bridge/ bridge]
| bridge是默认的桥接网络，当没有指定网络驱动，新启动的容器会连接到这个名称为bridge的bridge网络。也可以自定义一个网桥，只有连接到该网络的容器才能相互通信，从而起到隔离效果。自定义的网桥可以动态的连接或断开。 创建自定义网桥：<code>docker network create 网桥名称</code> 删除自定义网桥：<code>docker network rm 网桥名称</code> 查看网桥详细信息：<code>docker network inspect 网桥名称</code> 容器启动时连接到网桥：<code>--network 网桥名称</code> 运行中的容器连接到网桥：<code>docker network connect 网桥名称容器名称</code> 断开容器与网桥：<code>docker network disconnect 网桥名称容器名称</code> 注意：默认网桥bridge的<code>--link</code>命令已不建议使用，后面版本可能会被删除。默认网桥bridge内容器只能通过ip地址通信，需要添加<code>--link</code> 来添加名称，而自定义网桥可以使用容器名称或设置别名来通信。
| <code>docker network rm my-net</code>创建自定义网桥my-net 
|-
| 主机模式 [https://docs.docker.com/network/host/ host]
| 当使用host网络模式，容器共享主机的网络命名空间，而且容器不会分配自己的 IP 地址。如果容器中某个程序绑定到端口，直接访问主机的该端口即可。该模式端口全部暴露，端口映射不生效，即-p、--publish、-P和--publish-all选项都将被忽略。主机模式网络可用于优化性能，并且在容器需要处理大量端口的情况下，因为它不需要网络地址转换 (NAT)，并且没有为每个端口创建“用户空间代理”。 容器启动时设置：<code>--network host</code>或 <code>--net=host</code>
|
|-
| 覆盖模式 [https://docs.docker.com/network/overlay/ overlay]
| 跨主机的分布式网络。该模式允许连接到它的容器（包括群服务容器）通过加密安全地通信。
|
|-
| [https://docs.docker.com/network/macvlan/ macvlan]
|
|
|-
| [https://docs.docker.com/network/ipvlan/ ipvlan]
|
|
|-
| 禁用网络 [https://docs.docker.com/network/none/ none]
| 禁用容器的网络。 容器启动时设置：<code>--network none</code>
|
|-
| 网络插件 [https://docs.docker.com/engine/extend/plugins_services/#network-plugins Network plugins]
|
|
|}

{{了解更多
|[https://docs.docker.com/network/ Docker 文档：网络概览]
}}

==数据==
===概览===
默认情况下，所有文件将会存储在容器里的可写的容器层（container layer）。意味着：
* 数据与容器为一体。当容器删除时，数据会一起被删除。
* 该容器与其他程序（容器）数据交换难。
* 由于容器的写入层是与宿主机器紧紧耦合，所以难以移动数据到其他机器。
* 容器的写入层的是通过存储驱动（storage driver）管理文件系统。存储驱动会使用Linux内核的链合文件系统（union filesystem）进行挂载。相比起直接操作于宿主机器文件系统的数据卷（data volumes），这额外的抽象层将会降低性能。

Docker提供两种将数据存储在宿主机的方法：'''数据卷（volumes）'''和 '''绑定挂载（bind mounts）'''。另外，Linux用户还可使用'''tmpfs 挂载'''；window用户还可以使用命名管道（named pipe）。可用参数 <code>-v</code> 或 <code>--mount </code>来使用数据卷或绑定挂载，一般推荐--mount，更明确和详细。

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== 数据存储类型 ===
{| class="wikitable" style="width: 100%;
! 类型
! 描述
! 示例
|-
| 数据卷 [https://docs.docker.com/storage/volumes/ volumes]
| Docker 推荐的容器数据持久化方法，volumes完全由 Docker 管理。分为命名卷和匿名卷，匿名卷在容器删除时会被 Docker 引擎删除，或者启动容器时加入--rm时，容器退出匿名卷会自动删除。 创建数据卷：<code>docker volume create 卷名称</code> 列出数据卷： <code>docker volume ls</code> 数据卷详细信息：<code>docker volume inspect 卷名称 </code> 启动容器时连接卷（不存在卷会自动创建）：<code>--mount source=卷名称,target=/容器的/目录</code> 或 <code>-v 卷名称:/容器的/目录 </code> 启动容器时连接匿名卷：<code>-v /容器的/目录</code> 删除卷：<code>docker volume rm 卷名称</code> 清理没有使用的卷：<code>docker volume prune</code>
|
|-
| 绑定挂载 [https://docs.docker.com/storage/bind-mounts/ bind mounts]
| 将主机上的文件或目录挂载到容器中。主机的路径可以是相对路径。 启动容器时绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录</code> 或 <code>-v 主机/目录:/容器/目录</code> 只读绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录,readonly</code> 或 <code>-v 主机/目录:/容器/目录:ro</code>
|
|-
|tmpfs 挂载 [https://docs.docker.com/storage/tmpfs/ tmpfs mounts]
|tmpfs挂载是临时的，仅保留在主机内存中。当容器停止时，tmpfs挂载被移除，写入的文件不会被持久化。这对于临时存储您不想保留在主机或容器可写层中的敏感文件很有用。 可用命令 <code>-tmpfs </code> 或 <code>--mount </code>
|
|}

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== -v和--mount 参数 ===
使用命令 <code>docker inspect 容器名称</code> 可以查看容器详情，其中Mounts部分可以看到容器的挂载详细情况。
{| class="wikitable" style="width: 100%;
! 参数
! -v 或 --volume
! --mount
|-
! 特点
| 简洁，但有时出现混乱。
| 类型指定明确，推荐写法。
|-
! 支持类型
| <code>volumes</code>、<code>bind mounts</code>
| <code>volumes</code>、<code>bind mounts</code>、<code>tmpfs</code>
|-
! volumes
| <code>-v 卷名称:/容器的/目录 </code>
| <code>--mount source=卷名称,target=/容器的/目录</code>
|-
! bind mounts
| <code>-v 主机/目录:/容器/目录</code>
| <code>--mount type=bind,source=主机/目录,target=/容器/目录</code>
|-
! tmpfs mounts
| 不支持
| <code>--mount type=tmpfs,destination=/app</code>
|}
{{了解更多
|[https://docs.docker.com/storage/volumes/ Docker 文档：Use volumes]
|[https://docs.docker.com/storage/bind-mounts/ Docker 文档：Use bind mounts]
|[https://docs.docker.com/storage/tmpfs/ Docker 文档：Use tmpfs mounts]
}}
== 命令行 ==
{| class="wikitable"
! 名称
! 描述
! 示例
|-
|
|
|
|-
|
|
|
|-
|[https://docs.docker.com/engine/reference/commandline/system/ docker system]
| 管理docker 。如使用docker system prune能清理docker占用的磁盘空间，包括不使用的空间，构建镜像时的缓存等。
| docker system prune -a
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/cli/ Docker 文档：使用 Docker 命令行]
}}

==Compose==
Docker Compose 是用于定义和运行多容器 Docker 应用程序的工具。通过 Compose，您可以使用[[YML]]文件来配置应用程序需要的所有服务。然后，使用一个命令，就可以从[[YML]]文件配置中创建并启动所有服务。
=== 安装===
====版本====
{| class="wikitable"
! 名称
! 命令
! 描述
|-
| Compose 旧版
| docker-compose
| Compose 旧版为独立版，下载可执行文件使用。
|-
| Compose V2
| docker compose
| Compose V2也叫Compose插件版，作为插件和docker集成，安装升级方便。新版也提供更多的功能。
|}

{{了解更多
|[https://docs.docker.com/compose/ Docker Compose 文档]
}}

====Compose V2安装====
<syntaxhighlight lang="bash" >
# Ubuntu and Debian 安装
sudo apt-get update
sudo apt-get install docker-compose-plugin

# RPM-based distros 安装
sudo yum update
sudo yum install docker-compose-plugin

</syntaxhighlight>
{{了解更多
|[https://docs.docker.com/compose/install/ Docker 文档：安装Docker Compose]
}}
====Compose 旧版安装====
以Linux系统为例，使用<code>curl</code>命令在终端从GitHub上下载[https://github.com/docker/compose/releases Docker Compose]二进制文件。
<syntaxhighlight lang="bash" line='line'>
# 查看系统类型
echo $(uname -s)-$(uname -m)

# GitHub上右键复制系统对应版本，如linux-x86_64。如下载当前最新版compose 2.2.2
sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.2/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose

# 为compose程序文件添加执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 查看compose版本，验证是否安装成功
docker-compose --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/compose/install/other/ Docker 文档：安装 Compose 独立版]
}}

=== 快速入门 ===

===Compose 命令===
进入<code>docker-compose.yml</code>配置文件所在目录，执再行命令。
常用选项：
* -f, --file 指定其他名称配置文件。如：<code>docker compose -f docker-compose.prod.yml up</code>
*-p, --project-name 制定项目名称。如：<code>docker compose -p myproject up</code>

Compose 常用命令：
{| class="wikitable"
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/compose_up/ up]
| 自动执行一些列操作：构建镜像、创建服务、启动服务和关联服务相关容器。
| <code>docker compose up</code> <code>docker compose up -d</code> <code>docker compose -f docker-compose.dev.yml up --build </code>
|-
| stop
|
|
|-
| logs
|
| <code>logs</code>默认以不同颜色显示服务内容器的日志。
|-
| config
| 显示 Docker Compose 配置，包括环境变量。
| <code>docker compose config</code> 查看当前目录docker-compose.yml配置 <code>docker-compose -f docker-compose.dev.yml config</code> 查看当前docker-compose.dev.yml配置
|-
|
|
|
|-
| rm
|
| <code>docker compose rm -f</code> 强制删除服务内容器。 <code>docker rm -f $(docker compose ps -a -q)</code> 删除服务内所有容器。
|-
|
|
|
|}

{{了解更多
|[https://docs.docker.com/compose/reference/ Docker 文档：docker compose CLI ]
}}

==Swarm Mode==
Swarm Mode是Docker集群管理工具，从Docker1.2开始Docker Swarm内置到Docker中为Swarm Mode。

{{了解更多
|[https://docs.docker.com/engine/swarm/ Docker文档-Swarm mode]
}}
==安全==

==国内加速==
=== Docker CE镜像 ===
用于安装docker社区版软件。
{| class="wikitable"
! 名称
! 描述
|-
| 中国科学技术大学 USTC
| 手动安装时把 download.docker.com 地址换成 mirrors.ustc.edu.cn/docker-ce 即可。 地址：https://mirrors.ustc.edu.cn/docker-ce/ 文档：https://mirrors.ustc.edu.cn/help/docker-ce.html
|-
|
|
|-
|
|
|}
=== Docker Hub镜像 ===

=== 周边加速 ===
{| class="wikitable"
! 名称
! 描述
|-
| Dockerfile中apt更换软件源
| Debian换阿里源： <code>RUN sed -i s@/deb.debian.org/@/mirrors.aliyun.com/@g /etc/apt/sources.list</code>
|-
| Github镜像网站
| kgithub.com ：将Dockerfile中的github.com换成kgithub.com
|-
| 设置DNS
| echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf > /dev/null
|}

==实例==
====Docker安装Nginx====

====Docker安装Flask====
[[Flask]]是一个使用[[Python]]编写的轻量级Web应用框架。下面使用Dockerfile生成一个简单flask镜像，并启动。
<syntaxhighlight lang="bash">
#创建一个文件夹来保存项目
mkdir hello_flask
#利用 cd 命令切换到这个目录
cd hello_flask
</syntaxhighlight>接下来使用vim app.py命令创建一个app.py文件，内容如下：
<syntaxhighlight lang="python">
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
return 'Hello, World!'

if __name__=='__main__':
app.run(debug=True, host='0.0.0.0')
</syntaxhighlight>然后使用vim Dockerfile命令创建一个Dockerfile文件，内容如下：
<syntaxhighlight lang="bash">
app = Flask(__name__)

FROM python:alpine

COPY . /app
WORKDIR /app

RUN pip install Flask

ENTRYPOINT ["python"]
CMD ["app.py"]
</syntaxhighlight>现在hello_flask文件夹下有两个文件app.py和Dockerfile，
<syntaxhighlight lang="bash">
#在hello_flask文件夹下使用docker build命令生成镜像
docker build -t flask:1.1.1-min .

#使用 docker run 命令运行刚刚创建的镜像：
docker run --name flask -d -p 8080:5000 flask:1.1.1-min
</syntaxhighlight>
现在在浏览器打开ip;10000,可以看到Hello, World!

可以使用-v命令，把当前路径挂载到容器的/app目录，$PWD表示当前目录，比如现在的hello_flask。
docker run --name flask2 -d -p 8080:5000 -v $PWD:/app flask:1.1.1-min
在浏览器打开ip:8080可以看到“Hello, World!”，挂载后在主机中的hello_flask修改app.py，刷新网页就会看到更新的内容。修改文件时候要使用root权限不然会报错，sudo vim app.py

====Docker安装Mediawiki====
[[Mediawiki]]全球最著名的开源wiki程序，维基百科也使用该软件。

方法一：利用Docker Hub上现成镜像
<syntaxhighlight lang="bash">
#运行mediawiki镜像，没有就从docker hub下载mediawiki再运行
docker run --name some-mediawiki -p 8080:80 -d mediawiki

</syntaxhighlight>{{了解更多
|[https://hub.docker.com/_/mediawiki Docker Hub：Mediawiki ]
}}

==资源==
===官网===
*Docker 官网：https://www.docker.com
*Docker Hub：https://hub.docker.com/
*Docker 文档：https://docs.docker.com
*Docker 文档 > 参考：https://docs.docker.com/reference
*Docker 文档 > 示例：https://docs.docker.com/samples
*Docker CE 的 Github：https://github.com/docker/docker-ce

===相关网页===
*[https://zh.wikipedia.org/wiki/Docker 维基百科：Docker]
*[https://zh.wikipedia.org/wiki/操作系统层虚拟化维基百科：操作系统层虚拟化]

[[分类:编程工具]]

Docker

2026-04-18T15:44:12Z

Eric：/* 常用仓库 */

Docker 是一个开源软件的容器引擎软件。

==简介==
===时间轴===
* 2013年3月13日，发布初始版本。

===虚拟机与容器===
[[虚拟机]]可以在一种操作系统里面运行另一种操作系统，但虚拟机，资源占用多，启动慢。

容器是操作系统层虚拟化，容器化的优势在于占用服务器空间少，通常几秒内即可引导。

Docker 是一种容器的管理方式。下文的容器主要指Docker的容器。

===安装===
====CentOS====
官网建议安装在[[CentOS]] 7及以上的系统。如果之前有安装docker，先卸载之前版本。三种安装方法：
*添加Docker源进行安装，安装和升级方便，这是推荐的方法。
*下载RPM软件包，手动安装。
*官方一键安装脚本，一些测试和开发用户会选择这种方法。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#安装所需的软件包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

#安装containerd.io软件包，不然会报错requires containerd.io >= 1.2.2-3
sudo yum install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm

#设置官网的稳定版仓库源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

#可选，体验版和测试版默认是关闭的，可以通过命令打开，详细见文档。

#安装最新版本的docker CE
sudo yum install docker-ce

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

也可以使用dnf命令安装，dnf为下一代yum命令。
<syntaxhighlight lang="bash">
sudo dnf -y install dnf-plugins-core
sudo dnf install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce
sudo systemctl start docker
</syntaxhighlight>

方法二，下载RPM包，离线安装：
<syntaxhighlight lang="bash">
#在联网的计算机下载RPM软件包，从官网地址选一个版本下载：https://download.docker.com/linux/fedora/
#比如：docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#复制到计算机的某个目录，执行安装
sudo dnf -y install docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

方法三，使用脚本安装：
Docker提供脚本安装方式，快捷安装。
<syntaxhighlight lang="bash">
#下载脚本
curl -fsSL https://get.docker.com -o get-docker.sh
#运行脚本安装
sudo sh get-docker.sh

#如果以非root用户使用docker（推荐），需要添加一个用户到'docker'用户组中
#查看是否添加成功，如果添加当前登录的用户，需要重新登录，组权限才会生效。
sudo usermod -aG docker your-user-name

#查看是否安装成功
docker --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/engine/install/centos/ Docker文档-centos安装Docker引擎]
}}

====Ubuntu====
[[Ubuntu]]安装Docker也有三种方法，与[[CentOS]]安装docker类似。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#获取apt可用最新列表
sudo apt-get update
#使用apt安装下列软件包
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg-agent \
software-properties-common
#添加docker官方GPG密钥，验证密钥指纹9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
#添加docker的稳定源
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"

#获取apt可用最新列表
sudo apt-get update
#安装最新版的Docker CE
sudo apt-get install docker-ce docker-ce-cli containerd.io

#检验是否安装成功
sudo docker run hello-world
#使用非root用户使用docker，可以将用户添加到docker组：
sudo gpasswd -a ${USER} docker #将当前用户添加到docker组，重新登录后生效
sudo usermod -aG docker your-user #将其他用户添加到docker组
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/install/linux/docker-ce/ubuntu/ Docker文档-Ubuntu安装Docker CE]
}}

==快速入门==

==镜像==
镜像(Image)是只读文件，容器是运行在镜像之上，运行容器时会复制镜像然后启动。镜像的一些属性：
*REPOSITORY：表示镜像的仓库源
*TAG：镜像的标签
*IMAGE ID：镜像ID
*CREATED：镜像创建时间
*SIZE：镜像大小

当运行容器时，使用的镜像如果在本地中不存在，docker 就会自动从 docker 镜像仓库中下载，默认是从 Docker Hub 公共镜像源下载。

===镜像使用===
可以命令行输入<code>命令 --help</code>查看帮助，如在命令行输入<code>docker search --help</code>
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/image_ls/ docker image ls] [https://docs.docker.com/engine/reference/commandline/images/ docker images]
| '''查看镜像''' 列出本地主机上的镜像
| <code>docker image ls</code>查看本地镜像 <code>docker images -a </code>列出本地主机上的镜像，包括默认隐藏的中间镜像。
|-
| [https://docs.docker.com/engine/reference/commandline/tag/ docker tag] docker image tag
| '''创建引用标签''' 为镜像创建新标签，方便使用。
| <code>docker tag 0e1234567893 ubuntu:V20</code>为ID：0e1234567893的镜像加多个标签ubuntu:V20 <code>docker tag ubuntu:18.04 mytest/ubuntu:18</code>为ubuntu:18.04镜像添加标签mytest/ubuntu:18
|-
| docker image rm docker rmi
| '''删除镜像''' 删除镜像正在使用的镜像会报错
| <code>docker image rm Ubuntu</code> <code>docker rmi Ubuntu</code>
|-
| docker image prune
| '''清理镜像''' 删除未使用的镜像
| <code>docker image prune</code>删除未使用的镜像
|-
| [https://docs.docker.com/engine/reference/commandline/image_pull/ docker pull]
| '''下载镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上下载。
| <code>docker pull ubuntu</code>默认下载tag: latest的版本 <code>docker pull ubuntu:18.04</code>指定镜像版本
|-
| docker search
| '''搜索镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上搜索。 输出结果说明： NAME: 镜像仓库源的名称 DESCRIPTION: 镜像的描述 OFFICIAL: 是否docker官方发布 START: 表示点赞数量 AUTOMATED: 自动构建
| <code>docker search nginx</code>搜索nginx软件的镜像 <code>docker search --filter=is-offical=true mysql</code>搜索mysql软件的镜像 <code>docker search --filter=stars=100 mysql</code>搜索star超过100的mysql镜像
|-
|docker push
|'''上传镜像''' 默认上传到Docker镜像仓库[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。先注册一个免费Docker 账号，接下来可以在终端操作。
|<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
|-
| docker history
| '''镜像历史''' 查看制作镜像的命令 格式：<code>docker history [参数] 镜像</code>
|<code>docker history nginx</code>查看nginx镜像制作的历史
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/image/ Docker 参考：docker image]
|[https://docs.docker.com/engine/reference/commandline/images/ Docker 参考：docker images]
}}

===常用镜像===
====操作系统基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| busybox
|
|
|
|-
| alpine
| 5 MB
| Alpine Linux是一个面向安全的轻型的Linux发行版。Alpine不包含 bash 因此进入某个alpine docker容器，可以使用sh命令，如： <code>docker exec -it container_name sh</code>进入某个容器并运行sh。 <code>docker run -it -v data_volume:/data alpine:3.16.9 sh</code>启动一个容器，挂在data_volume卷到容器的/data目录。
| 官网：https://www.alpinelinux.org/ 镜像：https://hub.docker.com/_/alpine/
|-
| ubuntu
| 30 MB
|
|官网：http://www.ubuntu.com/ 镜像：https://hub.docker.com/_/ubuntu/
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

====编程语言基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| python
| 50 MB 350 MB 2.64G
|
| 镜像： https://hub.docker.com/_/python/
|-
| node
|
| Node.js是一个基于JavaScript的平台，用于服务器端和网络应用程序。
| 镜像：https://hub.docker.com/_/node/
|-
|
|
|
|
|-
|
|
|
|
|}

===制作镜像===
当docker镜像仓库没有想要的镜像，可以通过以下两种方式制作镜像。
*在已有容器中修改，再提交保存为新镜像。
*使用Dockerfile文件，从头创建一个新的镜像。

====容器打包为镜像====
修改容器，通过命令 docker commit 将容器打包为新镜像。如：
<syntaxhighlight lang="bash">
#启动一个名称ubuntu-18为容器，并进入容器终端
docker run --name ubuntu-18 -it ubuntu:18.04 /bin/bash

#在容器内修改，如更新软件，
apt-get update

#退出这个容器
exit

#提交打包镜像
docker commit ubuntu-18 ubuntu-updated
</syntaxhighlight>

====Dockerfile创建镜像====
Docker可以自动读取Dockerfile文件里的指令生成一个镜像。Dockerfile是一个文本文件，都是一些关于组装镜像的指令。通过docker build命令来生成一个镜像。

====Dockerfile语法====
Dockerfile文件格式如下：
# Comment 注释
INSTRUCTION arguments

注释使用#号，指令不区分大小写，但一般指令使用大写，这样容易和后面参数区分开来。

====Dockerfile指令====
{| class="wikitable" style="width: 100%;
!指令!!格式!!描述!!示例
|-
|[https://docs.docker.com/engine/reference/builder/#from FROM]
|FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
|初始化，设置基准镜像。这个指令必须放开头。
|FROM debian:buster-slim
|-
|[https://docs.docker.com/engine/reference/builder/#run RUN]
|RUN <command> 或 RUN ["executable", "param1", "param2"]
|执行命令
|RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'
|-
|[https://docs.docker.com/engine/reference/builder/#cmd CMD]
|CMD ["param1","param2"] CMD command param1 param2 CMD ["executable","param1","param2"]
|容器启动时执行的命令。该指令只能有一个，当有多个RUN指令只会执行最后一个
|
|-
|[https://docs.docker.com/engine/reference/builder/#label LABEL]
|LABEL <key>=<value> <key>=<value> <key>=<value> ...
|给镜像添加元数据。如添加一些作者信息，版本信息等。可以使用docker image inspect命令查看镜像所有信息，包括标签。
|LABEL maintainer="yourname@domain.com" version="1.0"
|-
|[https://docs.docker.com/engine/reference/builder/#expose EXPOSE]
|EXPOSE <port> [<port>/<protocol>...]
|开放容器某个端口，默认协议为TCP。运行主机可以通过docker run命令增加-p参数来对接这个端口。
|EXPOSE 80/udp
|-
|[https://docs.docker.com/engine/reference/builder/#env ENV]
|ENV <key> <value> ENV <key>=<value> ...
|设置环境变量
|ENV myName John Doe
|-
|[https://docs.docker.com/engine/reference/builder/#add ADD]
|ADD [--chown=<user>:<group>] <src>... <dest> ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件、目录或URLs到镜像中。src的路径支持Go语言的filepath.Match规则。
|ADD test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#copy COPY]
|COPY [--chown=<user>:<group>] <src>... <dest> COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件或目录到镜像中。src的路径支持Go语言的filepath.Match规则。
|COPY test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#entrypoint ENTRYPOINT]
|ENTRYPOINT ["executable", "param1", "param2"] ENTRYPOINT command param1 param2
|容器启动时执行的命令。
|ENTRYPOINT ["top", "-b"]
|-
|[https://docs.docker.com/engine/reference/builder/#volume VOLUME]
|VOLUME ["/data"]
|创建挂载点
|VOLUME /myvol
|-
|[https://docs.docker.com/engine/reference/builder/#user USER]
|USER <user>[:<group>] USER <UID>[:<GID>]
|设置启动容器的用户，可以是用户名或UID。
|USER username
|-
|[https://docs.docker.com/engine/reference/builder/#workdir WORKDIR]
|WORKDIR /path/to/workdir
|设置工作目录，对RUN, CMD, ENTRYPOINT, COPY 和 ADD指令有效。
|WORKDIR /home/foo/work
|-
|[https://docs.docker.com/engine/reference/builder/#arg ARG]
|ARG <name>[=<default value>]
|设置构建镜像时变量，构建docker build时使用--build-arg <varname>=<value>传递变量值。
|ARG user1=someuser
|-
|[https://docs.docker.com/engine/reference/builder/#onbuild ONBUILD]
|ONBUILD <INSTRUCTION>
|设置触发指令，当该镜像作为基准镜像，构建时执行。
|
|-
|[https://docs.docker.com/engine/reference/builder/#stopsignal STOPSIGNAL]
|STOPSIGNAL signal
|
|
|-
|[https://docs.docker.com/engine/reference/builder/#healthcheck HEALTHCHECK]
|HEALTHCHECK [OPTIONS] CMD command HEALTHCHECK NONE
|告诉dockers该镜像的容器正常工作状况
|<nowiki>HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost/ || exit 1 </nowiki>
|-
|[https://docs.docker.com/engine/reference/builder/#shell SHELL]
|
|
|
|-
|}

====docker build构建镜像====

{{了解更多
| [https://docs.docker.com/engine/reference/builder/ Docker参考：Dockerfile]
}}

== 容器 ==
容器（Container）是运行在镜像之上，运行容器时会复制镜像然后启动。
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/run/ docker run]
| '''运行容器''' docker run [参数] 镜像 [COMMAND] [ARG...] 从镜像启动一个新容器。该命令会检查本地是否有镜像，没有就从docker仓库中下载。 常用参数： <code>--name</code> 容器命名，如<code>--name test</code> <code>--restart</code> 重启策略，如停止后自动重启：<code>--restart=always</code> <code>-P</code> 绑定端口 <code>-v</code> 挂载
| <code>docker run -it ubuntu</code>使用 ubuntu 镜像启动一个容器 <code>docker run -it ubuntu /bin/bash</code>启动一个ubuntu容器，并进入终端。要退出容器里的终端输入exit。<code>docker run -itd --name ubuntu-test ubuntu /bin/bash</code>启动一个名称ubuntu-test为容器，并后台运行。参数-d表示后台运行。
|-
| [https://docs.docker.com/engine/reference/commandline/update/ docker update]
| '''更新容器''' 动态更新容器配置。 常用参数： <code>--memory</code> , <code>-m</code> 内存限制 <code>--restart</code> 重启策略
| <code>docker update --restart=unless-stopped mynginx</code> 配置mynginx容器重启策略为unless-stopped
|-
| docker start
| '''启动容器''' 启动已经停止的容器。
| <code>docker start dw3342531d3</code> 启动一个容器id为dw3342531d3的容器。
|-
| docker restart
|'''重启容器''' 重启正在运行的容器。
| <code>docker restart ubuntu-test</code> 重启容器ubuntu-test。
|-
| [https://docs.docker.com/engine/reference/commandline/ps/ docker ps]
|'''查看本地容器列表''' 重启正在运行的容器。 常用参数： <code>--no-trunc</code> 显示完整内容，不截断。
|<code>docker ps</code>查看正在运行的容器 <code>docker ps -a</code>查看所用容器，包括停止的 <code>docker ps --no-trunc</code>
|-
|[https://docs.docker.com/engine/reference/commandline/inspect/ docker inspect]
|'''查看容器信息''' 查看容器底层信息。它会返回一个 JSON 文件记录着 Docker 容器的配置和状态信息。 常用参数： <code>-f, --format </code> 使用Go语言template格式化输出。
|<code>docker inspect ubuntu-test</code> 查看ubuntu-test容器信息 <code><nowiki>docker inspect --format='{{.NetworkSettings.IPAddress}}' test2</nowiki></code> 查看test2容器ip <code><nowiki>docker inspect -f '{{.Name}} - {{range .NetworkSettings.Networks }} {{.IPAddress}} {{end}}' $(docker ps -aq)</nowiki></code> 查看所有容器ip地址。 <code><nowiki>docker inspect -f '{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' test2</nowiki></code> 查看test2容器MAC <code><nowiki>docker inspect --format='{{.LogPath}}' test2</nowiki></code> 查看test2容器的log地址 <code><nowiki>docker inspect -f '{{.Config.Image}}' test2</nowiki></code> 查看test2容器的镜像名称
|-
|[https://docs.docker.com/engine/reference/commandline/stats/ docker stats]
|'''实时统计容器使用资源''' 统计容器使用主机CUP、内存的百分比，通过网络发送和接收的数据量，从主机上的块设备读取和写入的数据量。
|<code>docker stats</code>
|-
|[https://docs.docker.com/engine/reference/commandline/logs/ docker logs]
|'''查看容器日志''' 查看容器内部的标准输出。
|<code>docker logs ubuntu-test</code>查看ubuntu-test容器内部的标准输出 <code>docker logs -f ubuntu-test</code>跟踪日志输出
|-
| docker top
|'''查看容器进程''' 查看容器内部运行的进程
| <code>docker top static_web</code> 查看static_web容器内部运行的进程
|-
| [https://docs.docker.com/engine/reference/commandline/exec/ docker exec]
|'''运行命令''' 在容器中运行命令。该命令退出容器终端，容器不会停止。
|<code>docker exec ubuntu-test ls</code>在ubuntu-test容器工作目录运行ls命令 <code>docker exec -it ubuntu-test bash</code>进入ubuntu-test容器交互式终端 <code>docker exec -u 0 -it test bash</code>以root用户进入名称为test的容器
|-
| docker attach
|'''附着终端''' 将本地终端标准输入、输出和错误流连接到运行的容器中。该命令退出容器终端，容器会停止，推荐使用<code>docker exec -it</code>。
|<code>docker attach ubuntu-test</code>
|-
|docker stop
|'''停止容器''' 停止运行中的容器
|<code>docker stop dw3342531d3</code> #停止一个id为dw3342531d3的容器 <code>docker stop $(docker ps -a -q)</code>停止所有运行中的容器
|-
|docker rm
|'''删除容器''' 删除容器，需要容器停止运行。参数-f表示强制删除，可以不用等容器停止后再删除。
|<code>docker rm ubuntu-test</code>删除ubuntu-test容器 <code>docker rm -f ubuntu-test</code>强制删除ubuntu-test容器 <code>docker rm -f $(docker ps -a -q)</code>'''注意，该命令会强制删除所有容器'''
|-
|docker container prune
|'''清理容器''' 删除所有停止的容器。
|<code>docker container prune</code>删除所有停止的容器。
|-
|docker commit
|'''容器构建镜像''' 将容器打包为一个镜像。
|<code>docker commit ubuntu-test ubuntu-updated</code>#将ubuntu-test容器打包为一个名称为ubuntu-updated镜像。
|}

== 仓库 ==
仓库（Repository）是集中存放镜像的地方。 Docker的官方镜像仓库为[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。

===Docker Hub===
大部分需求都可以通过在Docker Hub中直接下载镜像来实现。在[https://hub.docker.com https://hub.docker.com]免费注册一个 Docker 账号。接下来可以在终端操作
<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#在Docker Hub仓库中搜索使用docker search，这命令可以不登录。
docker search ubuntu

#下载镜像使用docker pull，这命令可以不登录。
docker pull ubuntu

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
可能出现问题：
*登录时出现：Error saving credentials: error storing credentials - err: exit status 1, out: `Cannot autolaunch D-Bus without X11 $DISPLAY`
执行下面命令即可：sudo apt install gnupg2 pass

*docker push报错：denied: requested access to the resource is denied
镜像名和用户名不匹配，使用tag将镜像名改为username/镜像名，username为个人的用户名，然后再推送，如：
docker tag ubuntu:18.04 username/ubuntu:18.04
docker push username/ubuntu:18.04

===其他公有镜像仓库===
==== 常用仓库 ====
{| class="wikitable" style="width: 100%;
! 提供方
! 仓库地址
! 描述
! 网址
|-
| 毫秒镜像
| docker.1ms.run
| 免费不需要登录，速度慢。付费12个月10元50G。
|https://1ms.run/
|-
| 阿里云
| https://xxxxxxxx.mirror.aliyuncs.com
| 需要注册阿里云，在镜像加速器可以看到仓库地址。
| [https://cr.console.aliyun.com/ 官网] [https://developer.aliyun.com/article/110806 文档]
|-
| 网易
| https://hub.c.163.com
|
| [https://sf.163.com/help/documents/56918246390157312 文档]
|-
| 百度云
| https://mirror.baidubce.com
|
|[https://cloud.baidu.com/doc/CCE/s/Yjxppt74z#如何使用dockerhub镜像加速器文档]
|-
| Google
|
|
|[https://cloud.google.com/container-registry/docs/pulling-cached-images 文档]
|}

==== 使用方法 ====
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| 拉取时指定仓库
| 单次有效 仓库地址不包含协议(如<code>https://</code>)，公有镜像仓库一般使用<code>library</code>。 如指定阿里镜像仓库拉取ubuntu： <code>docker pull xxxxxxxx.mirror.aliyuncs.com/library/ubuntu</code>
|-
| 编辑配置文件
| 永久有效 步骤： 1.编辑配置文件，<code>sudo vim /etc/docker/daemon.json</code>，输入如下内容<syntaxhighlight lang="json">
{
"registry-mirrors": [
"https://hub-mirror.c.163.com"
]
}
</syntaxhighlight>
2.重启docker服务，<code>sudo service docker restart</code> 3.查看是否成功，<code>docker info</code> 输出含有Registry Mirrors
|-
|
|
|}

===搭建私有镜像仓库===
<syntaxhighlight lang="bash" >
# 运行一个本地仓库
docker run -d -p 5000:5000 --restart always --name registry registry:3

# 现在，在Docker里使用，如推送，拉取
docker pull ubuntu
docker tag ubuntu localhost:5000/ubuntu
docker push localhost:5000/ubuntu
</syntaxhighlight>

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/
===镜像dockehub镜像仓库===
使用 Docker 启动 Registry 镜像加速服务
<syntaxhighlight lang="bash" >
sudo docker run -d \
--name dockerhub \
--restart=always \
-p 443:5000 \
-v /data/docker-registry:/var/lib/registry \
-v /your/domain/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.cer \
-e REGISTRY_HTTP_TLS_KEY=/certs/docker.yourdomain.com.key \
-e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
registry:3
</syntaxhighlight>

在其他电脑测试拉取镜像：
sudo docker pull yourdomain.com/library/hello-world

成功拉取后，可以配置 Docker 的默认镜像地址方便使用，没有成功查看运行日志<code>sudo docker logs dockerhub</code>。

进阶版本，使用registry + Nginx + HTTPS进行镜像加速。

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/

==网络==
===概览===
Docker的网络是可拔插的子系统，使用驱动程序。docker内置了几个驱动程序，提供了核心网络功能。
{| class="wikitable" style="width: 100%;
! 网络模式
! 描述
! 示例
|-
| 桥接模式 [https://docs.docker.com/network/bridge/ bridge]
| bridge是默认的桥接网络，当没有指定网络驱动，新启动的容器会连接到这个名称为bridge的bridge网络。也可以自定义一个网桥，只有连接到该网络的容器才能相互通信，从而起到隔离效果。自定义的网桥可以动态的连接或断开。 创建自定义网桥：<code>docker network create 网桥名称</code> 删除自定义网桥：<code>docker network rm 网桥名称</code> 查看网桥详细信息：<code>docker network inspect 网桥名称</code> 容器启动时连接到网桥：<code>--network 网桥名称</code> 运行中的容器连接到网桥：<code>docker network connect 网桥名称容器名称</code> 断开容器与网桥：<code>docker network disconnect 网桥名称容器名称</code> 注意：默认网桥bridge的<code>--link</code>命令已不建议使用，后面版本可能会被删除。默认网桥bridge内容器只能通过ip地址通信，需要添加<code>--link</code> 来添加名称，而自定义网桥可以使用容器名称或设置别名来通信。
| <code>docker network rm my-net</code>创建自定义网桥my-net 
|-
| 主机模式 [https://docs.docker.com/network/host/ host]
| 当使用host网络模式，容器共享主机的网络命名空间，而且容器不会分配自己的 IP 地址。如果容器中某个程序绑定到端口，直接访问主机的该端口即可。该模式端口全部暴露，端口映射不生效，即-p、--publish、-P和--publish-all选项都将被忽略。主机模式网络可用于优化性能，并且在容器需要处理大量端口的情况下，因为它不需要网络地址转换 (NAT)，并且没有为每个端口创建“用户空间代理”。 容器启动时设置：<code>--network host</code>或 <code>--net=host</code>
|
|-
| 覆盖模式 [https://docs.docker.com/network/overlay/ overlay]
| 跨主机的分布式网络。该模式允许连接到它的容器（包括群服务容器）通过加密安全地通信。
|
|-
| [https://docs.docker.com/network/macvlan/ macvlan]
|
|
|-
| [https://docs.docker.com/network/ipvlan/ ipvlan]
|
|
|-
| 禁用网络 [https://docs.docker.com/network/none/ none]
| 禁用容器的网络。 容器启动时设置：<code>--network none</code>
|
|-
| 网络插件 [https://docs.docker.com/engine/extend/plugins_services/#network-plugins Network plugins]
|
|
|}

{{了解更多
|[https://docs.docker.com/network/ Docker 文档：网络概览]
}}

==数据==
===概览===
默认情况下，所有文件将会存储在容器里的可写的容器层（container layer）。意味着：
* 数据与容器为一体。当容器删除时，数据会一起被删除。
* 该容器与其他程序（容器）数据交换难。
* 由于容器的写入层是与宿主机器紧紧耦合，所以难以移动数据到其他机器。
* 容器的写入层的是通过存储驱动（storage driver）管理文件系统。存储驱动会使用Linux内核的链合文件系统（union filesystem）进行挂载。相比起直接操作于宿主机器文件系统的数据卷（data volumes），这额外的抽象层将会降低性能。

Docker提供两种将数据存储在宿主机的方法：'''数据卷（volumes）'''和 '''绑定挂载（bind mounts）'''。另外，Linux用户还可使用'''tmpfs 挂载'''；window用户还可以使用命名管道（named pipe）。可用参数 <code>-v</code> 或 <code>--mount </code>来使用数据卷或绑定挂载，一般推荐--mount，更明确和详细。

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== 数据存储类型 ===
{| class="wikitable" style="width: 100%;
! 类型
! 描述
! 示例
|-
| 数据卷 [https://docs.docker.com/storage/volumes/ volumes]
| Docker 推荐的容器数据持久化方法，volumes完全由 Docker 管理。分为命名卷和匿名卷，匿名卷在容器删除时会被 Docker 引擎删除，或者启动容器时加入--rm时，容器退出匿名卷会自动删除。 创建数据卷：<code>docker volume create 卷名称</code> 列出数据卷： <code>docker volume ls</code> 数据卷详细信息：<code>docker volume inspect 卷名称 </code> 启动容器时连接卷（不存在卷会自动创建）：<code>--mount source=卷名称,target=/容器的/目录</code> 或 <code>-v 卷名称:/容器的/目录 </code> 启动容器时连接匿名卷：<code>-v /容器的/目录</code> 删除卷：<code>docker volume rm 卷名称</code> 清理没有使用的卷：<code>docker volume prune</code>
|
|-
| 绑定挂载 [https://docs.docker.com/storage/bind-mounts/ bind mounts]
| 将主机上的文件或目录挂载到容器中。主机的路径可以是相对路径。 启动容器时绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录</code> 或 <code>-v 主机/目录:/容器/目录</code> 只读绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录,readonly</code> 或 <code>-v 主机/目录:/容器/目录:ro</code>
|
|-
|tmpfs 挂载 [https://docs.docker.com/storage/tmpfs/ tmpfs mounts]
|tmpfs挂载是临时的，仅保留在主机内存中。当容器停止时，tmpfs挂载被移除，写入的文件不会被持久化。这对于临时存储您不想保留在主机或容器可写层中的敏感文件很有用。 可用命令 <code>-tmpfs </code> 或 <code>--mount </code>
|
|}

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== -v和--mount 参数 ===
使用命令 <code>docker inspect 容器名称</code> 可以查看容器详情，其中Mounts部分可以看到容器的挂载详细情况。
{| class="wikitable" style="width: 100%;
! 参数
! -v 或 --volume
! --mount
|-
! 特点
| 简洁，但有时出现混乱。
| 类型指定明确，推荐写法。
|-
! 支持类型
| <code>volumes</code>、<code>bind mounts</code>
| <code>volumes</code>、<code>bind mounts</code>、<code>tmpfs</code>
|-
! volumes
| <code>-v 卷名称:/容器的/目录 </code>
| <code>--mount source=卷名称,target=/容器的/目录</code>
|-
! bind mounts
| <code>-v 主机/目录:/容器/目录</code>
| <code>--mount type=bind,source=主机/目录,target=/容器/目录</code>
|-
! tmpfs mounts
| 不支持
| <code>--mount type=tmpfs,destination=/app</code>
|}
{{了解更多
|[https://docs.docker.com/storage/volumes/ Docker 文档：Use volumes]
|[https://docs.docker.com/storage/bind-mounts/ Docker 文档：Use bind mounts]
|[https://docs.docker.com/storage/tmpfs/ Docker 文档：Use tmpfs mounts]
}}
== 命令行 ==
{| class="wikitable"
! 名称
! 描述
! 示例
|-
|
|
|
|-
|
|
|
|-
|[https://docs.docker.com/engine/reference/commandline/system/ docker system]
| 管理docker 。如使用docker system prune能清理docker占用的磁盘空间，包括不使用的空间，构建镜像时的缓存等。
| docker system prune -a
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/cli/ Docker 文档：使用 Docker 命令行]
}}

==Compose==
Docker Compose 是用于定义和运行多容器 Docker 应用程序的工具。通过 Compose，您可以使用[[YML]]文件来配置应用程序需要的所有服务。然后，使用一个命令，就可以从[[YML]]文件配置中创建并启动所有服务。
=== 安装===
====版本====
{| class="wikitable"
! 名称
! 命令
! 描述
|-
| Compose 旧版
| docker-compose
| Compose 旧版为独立版，下载可执行文件使用。
|-
| Compose V2
| docker compose
| Compose V2也叫Compose插件版，作为插件和docker集成，安装升级方便。新版也提供更多的功能。
|}

{{了解更多
|[https://docs.docker.com/compose/ Docker Compose 文档]
}}

====Compose V2安装====
<syntaxhighlight lang="bash" >
# Ubuntu and Debian 安装
sudo apt-get update
sudo apt-get install docker-compose-plugin

# RPM-based distros 安装
sudo yum update
sudo yum install docker-compose-plugin

</syntaxhighlight>
{{了解更多
|[https://docs.docker.com/compose/install/ Docker 文档：安装Docker Compose]
}}
====Compose 旧版安装====
以Linux系统为例，使用<code>curl</code>命令在终端从GitHub上下载[https://github.com/docker/compose/releases Docker Compose]二进制文件。
<syntaxhighlight lang="bash" line='line'>
# 查看系统类型
echo $(uname -s)-$(uname -m)

# GitHub上右键复制系统对应版本，如linux-x86_64。如下载当前最新版compose 2.2.2
sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.2/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose

# 为compose程序文件添加执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 查看compose版本，验证是否安装成功
docker-compose --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/compose/install/other/ Docker 文档：安装 Compose 独立版]
}}

=== 快速入门 ===

===Compose 命令===
进入<code>docker-compose.yml</code>配置文件所在目录，执再行命令。
常用选项：
* -f, --file 指定其他名称配置文件。如：<code>docker compose -f docker-compose.prod.yml up</code>
*-p, --project-name 制定项目名称。如：<code>docker compose -p myproject up</code>

Compose 常用命令：
{| class="wikitable"
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/compose_up/ up]
| 自动执行一些列操作：构建镜像、创建服务、启动服务和关联服务相关容器。
| <code>docker compose up</code> <code>docker compose up -d</code> <code>docker compose -f docker-compose.dev.yml up --build </code>
|-
| stop
|
|
|-
| logs
|
| <code>logs</code>默认以不同颜色显示服务内容器的日志。
|-
| config
| 显示 Docker Compose 配置，包括环境变量。
| <code>docker compose config</code> 查看当前目录docker-compose.yml配置 <code>docker-compose -f docker-compose.dev.yml config</code> 查看当前docker-compose.dev.yml配置
|-
|
|
|
|-
| rm
|
| <code>docker compose rm -f</code> 强制删除服务内容器。 <code>docker rm -f $(docker compose ps -a -q)</code> 删除服务内所有容器。
|-
|
|
|
|}

{{了解更多
|[https://docs.docker.com/compose/reference/ Docker 文档：docker compose CLI ]
}}

==Swarm Mode==
Swarm Mode是Docker集群管理工具，从Docker1.2开始Docker Swarm内置到Docker中为Swarm Mode。

{{了解更多
|[https://docs.docker.com/engine/swarm/ Docker文档-Swarm mode]
}}
==安全==

==国内加速==
=== Docker CE镜像 ===
用于安装docker社区版软件。
{| class="wikitable"
! 名称
! 描述
|-
| 中国科学技术大学 USTC
| 手动安装时把 download.docker.com 地址换成 mirrors.ustc.edu.cn/docker-ce 即可。 地址：https://mirrors.ustc.edu.cn/docker-ce/ 文档：https://mirrors.ustc.edu.cn/help/docker-ce.html
|-
|
|
|-
|
|
|}
=== Docker Hub镜像 ===

=== 周边加速 ===
{| class="wikitable"
! 名称
! 描述
|-
| Dockerfile中apt更换软件源
| Debian换阿里源： <code>RUN sed -i s@/deb.debian.org/@/mirrors.aliyun.com/@g /etc/apt/sources.list</code>
|-
| Github镜像网站
| kgithub.com ：将Dockerfile中的github.com换成kgithub.com
|-
| 设置DNS
| echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf > /dev/null
|}

==实例==
====Docker安装Nginx====

====Docker安装Flask====
[[Flask]]是一个使用[[Python]]编写的轻量级Web应用框架。下面使用Dockerfile生成一个简单flask镜像，并启动。
<syntaxhighlight lang="bash">
#创建一个文件夹来保存项目
mkdir hello_flask
#利用 cd 命令切换到这个目录
cd hello_flask
</syntaxhighlight>接下来使用vim app.py命令创建一个app.py文件，内容如下：
<syntaxhighlight lang="python">
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
return 'Hello, World!'

if __name__=='__main__':
app.run(debug=True, host='0.0.0.0')
</syntaxhighlight>然后使用vim Dockerfile命令创建一个Dockerfile文件，内容如下：
<syntaxhighlight lang="bash">
app = Flask(__name__)

FROM python:alpine

COPY . /app
WORKDIR /app

RUN pip install Flask

ENTRYPOINT ["python"]
CMD ["app.py"]
</syntaxhighlight>现在hello_flask文件夹下有两个文件app.py和Dockerfile，
<syntaxhighlight lang="bash">
#在hello_flask文件夹下使用docker build命令生成镜像
docker build -t flask:1.1.1-min .

#使用 docker run 命令运行刚刚创建的镜像：
docker run --name flask -d -p 8080:5000 flask:1.1.1-min
</syntaxhighlight>
现在在浏览器打开ip;10000,可以看到Hello, World!

可以使用-v命令，把当前路径挂载到容器的/app目录，$PWD表示当前目录，比如现在的hello_flask。
docker run --name flask2 -d -p 8080:5000 -v $PWD:/app flask:1.1.1-min
在浏览器打开ip:8080可以看到“Hello, World!”，挂载后在主机中的hello_flask修改app.py，刷新网页就会看到更新的内容。修改文件时候要使用root权限不然会报错，sudo vim app.py

====Docker安装Mediawiki====
[[Mediawiki]]全球最著名的开源wiki程序，维基百科也使用该软件。

方法一：利用Docker Hub上现成镜像
<syntaxhighlight lang="bash">
#运行mediawiki镜像，没有就从docker hub下载mediawiki再运行
docker run --name some-mediawiki -p 8080:80 -d mediawiki

</syntaxhighlight>{{了解更多
|[https://hub.docker.com/_/mediawiki Docker Hub：Mediawiki ]
}}

==资源==
===官网===
*Docker 官网：https://www.docker.com
*Docker Hub：https://hub.docker.com/
*Docker 文档：https://docs.docker.com
*Docker 文档 > 参考：https://docs.docker.com/reference
*Docker 文档 > 示例：https://docs.docker.com/samples
*Docker CE 的 Github：https://github.com/docker/docker-ce

===相关网页===
*[https://zh.wikipedia.org/wiki/Docker 维基百科：Docker]
*[https://zh.wikipedia.org/wiki/操作系统层虚拟化维基百科：操作系统层虚拟化]

[[分类:编程工具]]

Nameslio

2026-04-17T12:18:42Z

Eric：/* 使用API示例 */

Nameslio是一家[[域名]]注册商和网络托管公司。

==API==
* https://www.namesilo.com/api-reference#domains/register-domain

===使用API示例===
使用python，添加或修改域名主机的A记录，如abc.abc.com设置ip为x.x.x.x:
<syntaxhighlight lang="python" >
import urllib.request
import urllib.parse
import json
import os

BASE_URL = "https://www.namesilo.com/api/"

# ========== 辅助函数 ==========
def load_dotenv(filepath=".env"):
"""手动解析 .env 文件"""
if not os.path.exists(filepath):
return
with open(filepath, "r") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
if "=" in line:
key, value = line.split("=", 1)
os.environ[key.strip()] = value.strip().strip("\"'")

def check_success(res):
code = res.get("reply", {}).get("code")
if code != 300:
raise Exception(f"API失败: code={code}, res={res}")
else:
# print(f'成功返回：{res["reply"].get("resource_record", [])}')
return True

def _request(endpoint, params):
api_key = os.getenv("NAMESILO_API_KEY")
if not api_key:
raise ValueError("请在 .env 中设置 NAMESILO_API_KEY")
params.update({
"version": "1",
"type": "json", # 推荐用 json，比 xml 好处理
"key": api_key
})

url = BASE_URL + endpoint + "?" + urllib.parse.urlencode(params)
# 测试使用，链接含有APIkey
# print(f"正在请求：{url}")

req = urllib.request.Request(
url,
headers={
"User-Agent": "Mozilla/5.0" # 关键！
}
)

with urllib.request.urlopen(req) as resp:
return json.loads(resp.read().decode())

def upsert_a_record(domain, host, ip, ttl=3600):

# 1️⃣ 查询记录
res = _request("dnsListRecords", {
"domain": domain
})

check_success(res)

records = res["reply"].get("resource_record", [])
if isinstance(records, dict): # 只有一条时会是 dict
records = [records]

record_id = None

# 2️⃣ 查找已有记录
for r in records:
if r["type"] == "A" and r["host"] == host:
if r["value"] == ip:
print("记录已存在, 无需更新")
return True
record_id = r["record_id"]

# 3️⃣ 更新
if record_id:
res = _request("dnsUpdateRecord", {
"domain": domain,
"rrid": record_id,
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# 4️⃣ 新增
else:
res = _request("dnsAddRecord", {
"domain": domain,
"rrtype": "A",
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# ========== 使用示例 ==========

if __name__ == "__main__":
# 加载 .env 文件
load_dotenv()

upsert_a_record(
domain=os.getenv("DOMAIN"), # 如: example.com
host=os.getenv("SUBDOMAIN"), # 如: www
ip=os.getenv("IP_ADDRESS"), # 如: 100.100.100.100
)
</syntaxhighlight>
密钥不放程序文件里，放.env文件：
<syntaxhighlight lang="python" >
NAMESILO_API_KEY=xxx
DOMAIN=xxx
SUBDOMAIN=xxx
IP_ADDRESS=xxx
</syntaxhighlight>

Nameslio

2026-04-17T11:51:17Z

Eric：

Nameslio是一家[[域名]]注册商和网络托管公司。

==API==
* https://www.namesilo.com/api-reference#domains/register-domain

===使用API示例===
使用python，添加或修改域名主机的A记录，如abc.abc.com设置ip为x.x.x.x:
<syntaxhighlight lang="python" >
import urllib.request
import urllib.parse
import json
import os

BASE_URL = "https://www.namesilo.com/api/"

# ========== 辅助函数 ==========
def load_dotenv(filepath=".env"):
"""手动解析 .env 文件"""
if not os.path.exists(filepath):
return
with open(filepath, "r") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
if "=" in line:
key, value = line.split("=", 1)
os.environ[key.strip()] = value.strip().strip("\"'")

def check_success(res):
code = res.get("reply", {}).get("code")
if code != 300:
raise Exception(f"API失败: code={code}, res={res}")

def _request(endpoint, params):
api_key = os.getenv("NAMESILO_API_KEY")
if not api_key:
raise ValueError("请在 .env 中设置 NAMESILO_API_KEY")
params.update({
"version": "1",
"type": "json", # 推荐用 json，比 xml 好处理
"key": api_key
})

url = BASE_URL + endpoint + "?" + urllib.parse.urlencode(params)
print(f"正在请求：{url}")

req = urllib.request.Request(
url,
headers={
"User-Agent": "Mozilla/5.0" # 不加请求头，namesilo会拒绝
}
)

with urllib.request.urlopen(req) as resp:
return json.loads(resp.read().decode())

def upsert_a_record(domain, host, ip, ttl=3600):
full_host = f"{host}.{domain}" if host != "@" else domain

# 1️⃣ 查询记录
res = _request("dnsListRecords", {
"domain": domain
})

check_success(res)

records = res["reply"].get("resource_record", [])
if isinstance(records, dict): # 只有一条时会是 dict
records = [records]

record_id = None

# 2️⃣ 查找已有记录
for r in records:
if r["type"] == "A" and r["host"] == full_host:
record_id = r["record_id"]
break

# 3️⃣ 更新
if record_id:
res = _request("dnsUpdateRecord", {
"domain": domain,
"rrid": record_id,
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# 4️⃣ 新增
else:
res = _request("dnsAddRecord", {
"domain": domain,
"rrtype": "A",
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# ========== 使用示例 ==========

if __name__ == "__main__":
# 加载 .env 文件
load_dotenv()

# 配置参数
DOMAIN = os.getenv("DOMAIN")
SUBDOMAIN = os.getenv("SUBDOMAIN")
IP_ADDRESS = os.getenv("IP_ADDRESS")

upsert_a_record(
domain=DOMAIN,
host=SUBDOMAIN,
ip=IP_ADDRESS
)
</syntaxhighlight>
密钥不放程序文件里，放.env文件：
<syntaxhighlight lang="python" >
NAMESILO_API_KEY=xxx
DOMAIN=xxx
SUBDOMAIN=xxx
IP_ADDRESS=xxx
</syntaxhighlight>

Nameslio

2026-04-17T11:49:51Z

Eric：创建页面，内容为“Nameslio是一家域名注册商和网络托管公司。 ==API== ===使用API示例=== 使用python，添加或修改域名主机的A记录，如abc.abc.com设置ip为x.x.x.x: <syntaxhighlight lang="python" > import urllib.request import urllib.parse import json import os BASE_URL = "https://www.namesilo.com/api/" # ========== 辅助函数 ========== def load_dotenv(filepath=".env"): """手动解析 .env 文件""" if not os.path.exists(filepath)…”

Nameslio是一家[[域名]]注册商和网络托管公司。

==API==
===使用API示例===
使用python，添加或修改域名主机的A记录，如abc.abc.com设置ip为x.x.x.x:
<syntaxhighlight lang="python" >
import urllib.request
import urllib.parse
import json
import os

BASE_URL = "https://www.namesilo.com/api/"

# ========== 辅助函数 ==========
def load_dotenv(filepath=".env"):
"""手动解析 .env 文件"""
if not os.path.exists(filepath):
return
with open(filepath, "r") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
if "=" in line:
key, value = line.split("=", 1)
os.environ[key.strip()] = value.strip().strip("\"'")

def check_success(res):
code = res.get("reply", {}).get("code")
if code != 300:
raise Exception(f"API失败: code={code}, res={res}")

def _request(endpoint, params):
api_key = os.getenv("NAMESILO_API_KEY")
if not api_key:
raise ValueError("请在 .env 中设置 NAMESILO_API_KEY")
params.update({
"version": "1",
"type": "json", # 推荐用 json，比 xml 好处理
"key": api_key
})

url = BASE_URL + endpoint + "?" + urllib.parse.urlencode(params)
print(f"正在请求：{url}")

req = urllib.request.Request(
url,
headers={
"User-Agent": "Mozilla/5.0" # 不加请求头，namesilo会拒绝
}
)

with urllib.request.urlopen(req) as resp:
return json.loads(resp.read().decode())

def upsert_a_record(domain, host, ip, ttl=3600):
full_host = f"{host}.{domain}" if host != "@" else domain

# 1️⃣ 查询记录
res = _request("dnsListRecords", {
"domain": domain
})

check_success(res)

records = res["reply"].get("resource_record", [])
if isinstance(records, dict): # 只有一条时会是 dict
records = [records]

record_id = None

# 2️⃣ 查找已有记录
for r in records:
if r["type"] == "A" and r["host"] == full_host:
record_id = r["record_id"]
break

# 3️⃣ 更新
if record_id:
res = _request("dnsUpdateRecord", {
"domain": domain,
"rrid": record_id,
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# 4️⃣ 新增
else:
res = _request("dnsAddRecord", {
"domain": domain,
"rrtype": "A",
"rrhost": host,
"rrvalue": ip,
"rrttl": ttl
})

check_success(res)

# ========== 使用示例 ==========

if __name__ == "__main__":
# 加载 .env 文件
load_dotenv()

# 配置参数
DOMAIN = os.getenv("DOMAIN")
SUBDOMAIN = os.getenv("SUBDOMAIN")
IP_ADDRESS = os.getenv("IP_ADDRESS")

upsert_a_record(
domain=DOMAIN,
host=SUBDOMAIN,
ip=IP_ADDRESS
)
</syntaxhighlight>
密钥不放程序文件里，放.env文件：
<syntaxhighlight lang="python" >
NAMESILO_API_KEY=xxx
DOMAIN=xxx
SUBDOMAIN=xxx
IP_ADDRESS=xxx
</syntaxhighlight>

Docker

2026-04-17T05:16:56Z

Eric：/* 仓库 */

Docker 是一个开源软件的容器引擎软件。

==简介==
===时间轴===
* 2013年3月13日，发布初始版本。

===虚拟机与容器===
[[虚拟机]]可以在一种操作系统里面运行另一种操作系统，但虚拟机，资源占用多，启动慢。

容器是操作系统层虚拟化，容器化的优势在于占用服务器空间少，通常几秒内即可引导。

Docker 是一种容器的管理方式。下文的容器主要指Docker的容器。

===安装===
====CentOS====
官网建议安装在[[CentOS]] 7及以上的系统。如果之前有安装docker，先卸载之前版本。三种安装方法：
*添加Docker源进行安装，安装和升级方便，这是推荐的方法。
*下载RPM软件包，手动安装。
*官方一键安装脚本，一些测试和开发用户会选择这种方法。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#安装所需的软件包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

#安装containerd.io软件包，不然会报错requires containerd.io >= 1.2.2-3
sudo yum install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm

#设置官网的稳定版仓库源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

#可选，体验版和测试版默认是关闭的，可以通过命令打开，详细见文档。

#安装最新版本的docker CE
sudo yum install docker-ce

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

也可以使用dnf命令安装，dnf为下一代yum命令。
<syntaxhighlight lang="bash">
sudo dnf -y install dnf-plugins-core
sudo dnf install https://download.docker.com/linux/fedora/30/x86_64/stable/Packages/containerd.io-1.2.6-3.3.fc30.x86_64.rpm
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce
sudo systemctl start docker
</syntaxhighlight>

方法二，下载RPM包，离线安装：
<syntaxhighlight lang="bash">
#在联网的计算机下载RPM软件包，从官网地址选一个版本下载：https://download.docker.com/linux/fedora/
#比如：docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#复制到计算机的某个目录，执行安装
sudo dnf -y install docker-ce-cli-19.03.4-3.fc31.x86_64.rpm

#启动守护进程
sudo systemctl start docker
</syntaxhighlight>

方法三，使用脚本安装：
Docker提供脚本安装方式，快捷安装。
<syntaxhighlight lang="bash">
#下载脚本
curl -fsSL https://get.docker.com -o get-docker.sh
#运行脚本安装
sudo sh get-docker.sh

#如果以非root用户使用docker（推荐），需要添加一个用户到'docker'用户组中
#查看是否添加成功，如果添加当前登录的用户，需要重新登录，组权限才会生效。
sudo usermod -aG docker your-user-name

#查看是否安装成功
docker --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/engine/install/centos/ Docker文档-centos安装Docker引擎]
}}

====Ubuntu====
[[Ubuntu]]安装Docker也有三种方法，与[[CentOS]]安装docker类似。

方法一，添加Docker源进行安装：
<syntaxhighlight lang="bash">
#获取apt可用最新列表
sudo apt-get update
#使用apt安装下列软件包
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg-agent \
software-properties-common
#添加docker官方GPG密钥，验证密钥指纹9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
#添加docker的稳定源
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"

#获取apt可用最新列表
sudo apt-get update
#安装最新版的Docker CE
sudo apt-get install docker-ce docker-ce-cli containerd.io

#检验是否安装成功
sudo docker run hello-world
#使用非root用户使用docker，可以将用户添加到docker组：
sudo gpasswd -a ${USER} docker #将当前用户添加到docker组，重新登录后生效
sudo usermod -aG docker your-user #将其他用户添加到docker组
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/install/linux/docker-ce/ubuntu/ Docker文档-Ubuntu安装Docker CE]
}}

==快速入门==

==镜像==
镜像(Image)是只读文件，容器是运行在镜像之上，运行容器时会复制镜像然后启动。镜像的一些属性：
*REPOSITORY：表示镜像的仓库源
*TAG：镜像的标签
*IMAGE ID：镜像ID
*CREATED：镜像创建时间
*SIZE：镜像大小

当运行容器时，使用的镜像如果在本地中不存在，docker 就会自动从 docker 镜像仓库中下载，默认是从 Docker Hub 公共镜像源下载。

===镜像使用===
可以命令行输入<code>命令 --help</code>查看帮助，如在命令行输入<code>docker search --help</code>
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/image_ls/ docker image ls] [https://docs.docker.com/engine/reference/commandline/images/ docker images]
| '''查看镜像''' 列出本地主机上的镜像
| <code>docker image ls</code>查看本地镜像 <code>docker images -a </code>列出本地主机上的镜像，包括默认隐藏的中间镜像。
|-
| [https://docs.docker.com/engine/reference/commandline/tag/ docker tag] docker image tag
| '''创建引用标签''' 为镜像创建新标签，方便使用。
| <code>docker tag 0e1234567893 ubuntu:V20</code>为ID：0e1234567893的镜像加多个标签ubuntu:V20 <code>docker tag ubuntu:18.04 mytest/ubuntu:18</code>为ubuntu:18.04镜像添加标签mytest/ubuntu:18
|-
| docker image rm docker rmi
| '''删除镜像''' 删除镜像正在使用的镜像会报错
| <code>docker image rm Ubuntu</code> <code>docker rmi Ubuntu</code>
|-
| docker image prune
| '''清理镜像''' 删除未使用的镜像
| <code>docker image prune</code>删除未使用的镜像
|-
| [https://docs.docker.com/engine/reference/commandline/image_pull/ docker pull]
| '''下载镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上下载。
| <code>docker pull ubuntu</code>默认下载tag: latest的版本 <code>docker pull ubuntu:18.04</code>指定镜像版本
|-
| docker search
| '''搜索镜像''' 默认从Docker镜像仓库[https://hub.docker.com/ Docker Hub]上搜索。 输出结果说明： NAME: 镜像仓库源的名称 DESCRIPTION: 镜像的描述 OFFICIAL: 是否docker官方发布 START: 表示点赞数量 AUTOMATED: 自动构建
| <code>docker search nginx</code>搜索nginx软件的镜像 <code>docker search --filter=is-offical=true mysql</code>搜索mysql软件的镜像 <code>docker search --filter=stars=100 mysql</code>搜索star超过100的mysql镜像
|-
|docker push
|'''上传镜像''' 默认上传到Docker镜像仓库[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。先注册一个免费Docker 账号，接下来可以在终端操作。
|<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
|-
| docker history
| '''镜像历史''' 查看制作镜像的命令 格式：<code>docker history [参数] 镜像</code>
|<code>docker history nginx</code>查看nginx镜像制作的历史
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/image/ Docker 参考：docker image]
|[https://docs.docker.com/engine/reference/commandline/images/ Docker 参考：docker images]
}}

===常用镜像===
====操作系统基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| busybox
|
|
|
|-
| alpine
| 5 MB
| Alpine Linux是一个面向安全的轻型的Linux发行版。Alpine不包含 bash 因此进入某个alpine docker容器，可以使用sh命令，如： <code>docker exec -it container_name sh</code>进入某个容器并运行sh。 <code>docker run -it -v data_volume:/data alpine:3.16.9 sh</code>启动一个容器，挂在data_volume卷到容器的/data目录。
| 官网：https://www.alpinelinux.org/ 镜像：https://hub.docker.com/_/alpine/
|-
| ubuntu
| 30 MB
|
|官网：http://www.ubuntu.com/ 镜像：https://hub.docker.com/_/ubuntu/
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

====编程语言基础镜像====
{| class="wikitable"
! 镜像名称
! 大小
! 描述
! 网址
|-
| python
| 50 MB 350 MB 2.64G
|
| 镜像： https://hub.docker.com/_/python/
|-
| node
|
| Node.js是一个基于JavaScript的平台，用于服务器端和网络应用程序。
| 镜像：https://hub.docker.com/_/node/
|-
|
|
|
|
|-
|
|
|
|
|}

===制作镜像===
当docker镜像仓库没有想要的镜像，可以通过以下两种方式制作镜像。
*在已有容器中修改，再提交保存为新镜像。
*使用Dockerfile文件，从头创建一个新的镜像。

====容器打包为镜像====
修改容器，通过命令 docker commit 将容器打包为新镜像。如：
<syntaxhighlight lang="bash">
#启动一个名称ubuntu-18为容器，并进入容器终端
docker run --name ubuntu-18 -it ubuntu:18.04 /bin/bash

#在容器内修改，如更新软件，
apt-get update

#退出这个容器
exit

#提交打包镜像
docker commit ubuntu-18 ubuntu-updated
</syntaxhighlight>

====Dockerfile创建镜像====
Docker可以自动读取Dockerfile文件里的指令生成一个镜像。Dockerfile是一个文本文件，都是一些关于组装镜像的指令。通过docker build命令来生成一个镜像。

====Dockerfile语法====
Dockerfile文件格式如下：
# Comment 注释
INSTRUCTION arguments

注释使用#号，指令不区分大小写，但一般指令使用大写，这样容易和后面参数区分开来。

====Dockerfile指令====
{| class="wikitable" style="width: 100%;
!指令!!格式!!描述!!示例
|-
|[https://docs.docker.com/engine/reference/builder/#from FROM]
|FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
|初始化，设置基准镜像。这个指令必须放开头。
|FROM debian:buster-slim
|-
|[https://docs.docker.com/engine/reference/builder/#run RUN]
|RUN <command> 或 RUN ["executable", "param1", "param2"]
|执行命令
|RUN /bin/bash -c 'source $HOME/.bashrc; echo $HOME'
|-
|[https://docs.docker.com/engine/reference/builder/#cmd CMD]
|CMD ["param1","param2"] CMD command param1 param2 CMD ["executable","param1","param2"]
|容器启动时执行的命令。该指令只能有一个，当有多个RUN指令只会执行最后一个
|
|-
|[https://docs.docker.com/engine/reference/builder/#label LABEL]
|LABEL <key>=<value> <key>=<value> <key>=<value> ...
|给镜像添加元数据。如添加一些作者信息，版本信息等。可以使用docker image inspect命令查看镜像所有信息，包括标签。
|LABEL maintainer="yourname@domain.com" version="1.0"
|-
|[https://docs.docker.com/engine/reference/builder/#expose EXPOSE]
|EXPOSE <port> [<port>/<protocol>...]
|开放容器某个端口，默认协议为TCP。运行主机可以通过docker run命令增加-p参数来对接这个端口。
|EXPOSE 80/udp
|-
|[https://docs.docker.com/engine/reference/builder/#env ENV]
|ENV <key> <value> ENV <key>=<value> ...
|设置环境变量
|ENV myName John Doe
|-
|[https://docs.docker.com/engine/reference/builder/#add ADD]
|ADD [--chown=<user>:<group>] <src>... <dest> ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件、目录或URLs到镜像中。src的路径支持Go语言的filepath.Match规则。
|ADD test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#copy COPY]
|COPY [--chown=<user>:<group>] <src>... <dest> COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]
|复制文件或目录到镜像中。src的路径支持Go语言的filepath.Match规则。
|COPY test.txt /etc/test/ 拷贝主机的test.txt文件到镜像/etc/test/目录中
|-
|[https://docs.docker.com/engine/reference/builder/#entrypoint ENTRYPOINT]
|ENTRYPOINT ["executable", "param1", "param2"] ENTRYPOINT command param1 param2
|容器启动时执行的命令。
|ENTRYPOINT ["top", "-b"]
|-
|[https://docs.docker.com/engine/reference/builder/#volume VOLUME]
|VOLUME ["/data"]
|创建挂载点
|VOLUME /myvol
|-
|[https://docs.docker.com/engine/reference/builder/#user USER]
|USER <user>[:<group>] USER <UID>[:<GID>]
|设置启动容器的用户，可以是用户名或UID。
|USER username
|-
|[https://docs.docker.com/engine/reference/builder/#workdir WORKDIR]
|WORKDIR /path/to/workdir
|设置工作目录，对RUN, CMD, ENTRYPOINT, COPY 和 ADD指令有效。
|WORKDIR /home/foo/work
|-
|[https://docs.docker.com/engine/reference/builder/#arg ARG]
|ARG <name>[=<default value>]
|设置构建镜像时变量，构建docker build时使用--build-arg <varname>=<value>传递变量值。
|ARG user1=someuser
|-
|[https://docs.docker.com/engine/reference/builder/#onbuild ONBUILD]
|ONBUILD <INSTRUCTION>
|设置触发指令，当该镜像作为基准镜像，构建时执行。
|
|-
|[https://docs.docker.com/engine/reference/builder/#stopsignal STOPSIGNAL]
|STOPSIGNAL signal
|
|
|-
|[https://docs.docker.com/engine/reference/builder/#healthcheck HEALTHCHECK]
|HEALTHCHECK [OPTIONS] CMD command HEALTHCHECK NONE
|告诉dockers该镜像的容器正常工作状况
|<nowiki>HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost/ || exit 1 </nowiki>
|-
|[https://docs.docker.com/engine/reference/builder/#shell SHELL]
|
|
|
|-
|}

====docker build构建镜像====

{{了解更多
| [https://docs.docker.com/engine/reference/builder/ Docker参考：Dockerfile]
}}

== 容器 ==
容器（Container）是运行在镜像之上，运行容器时会复制镜像然后启动。
{| class="wikitable" style="width: 100%;
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/run/ docker run]
| '''运行容器''' docker run [参数] 镜像 [COMMAND] [ARG...] 从镜像启动一个新容器。该命令会检查本地是否有镜像，没有就从docker仓库中下载。 常用参数： <code>--name</code> 容器命名，如<code>--name test</code> <code>--restart</code> 重启策略，如停止后自动重启：<code>--restart=always</code> <code>-P</code> 绑定端口 <code>-v</code> 挂载
| <code>docker run -it ubuntu</code>使用 ubuntu 镜像启动一个容器 <code>docker run -it ubuntu /bin/bash</code>启动一个ubuntu容器，并进入终端。要退出容器里的终端输入exit。<code>docker run -itd --name ubuntu-test ubuntu /bin/bash</code>启动一个名称ubuntu-test为容器，并后台运行。参数-d表示后台运行。
|-
| [https://docs.docker.com/engine/reference/commandline/update/ docker update]
| '''更新容器''' 动态更新容器配置。 常用参数： <code>--memory</code> , <code>-m</code> 内存限制 <code>--restart</code> 重启策略
| <code>docker update --restart=unless-stopped mynginx</code> 配置mynginx容器重启策略为unless-stopped
|-
| docker start
| '''启动容器''' 启动已经停止的容器。
| <code>docker start dw3342531d3</code> 启动一个容器id为dw3342531d3的容器。
|-
| docker restart
|'''重启容器''' 重启正在运行的容器。
| <code>docker restart ubuntu-test</code> 重启容器ubuntu-test。
|-
| [https://docs.docker.com/engine/reference/commandline/ps/ docker ps]
|'''查看本地容器列表''' 重启正在运行的容器。 常用参数： <code>--no-trunc</code> 显示完整内容，不截断。
|<code>docker ps</code>查看正在运行的容器 <code>docker ps -a</code>查看所用容器，包括停止的 <code>docker ps --no-trunc</code>
|-
|[https://docs.docker.com/engine/reference/commandline/inspect/ docker inspect]
|'''查看容器信息''' 查看容器底层信息。它会返回一个 JSON 文件记录着 Docker 容器的配置和状态信息。 常用参数： <code>-f, --format </code> 使用Go语言template格式化输出。
|<code>docker inspect ubuntu-test</code> 查看ubuntu-test容器信息 <code><nowiki>docker inspect --format='{{.NetworkSettings.IPAddress}}' test2</nowiki></code> 查看test2容器ip <code><nowiki>docker inspect -f '{{.Name}} - {{range .NetworkSettings.Networks }} {{.IPAddress}} {{end}}' $(docker ps -aq)</nowiki></code> 查看所有容器ip地址。 <code><nowiki>docker inspect -f '{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' test2</nowiki></code> 查看test2容器MAC <code><nowiki>docker inspect --format='{{.LogPath}}' test2</nowiki></code> 查看test2容器的log地址 <code><nowiki>docker inspect -f '{{.Config.Image}}' test2</nowiki></code> 查看test2容器的镜像名称
|-
|[https://docs.docker.com/engine/reference/commandline/stats/ docker stats]
|'''实时统计容器使用资源''' 统计容器使用主机CUP、内存的百分比，通过网络发送和接收的数据量，从主机上的块设备读取和写入的数据量。
|<code>docker stats</code>
|-
|[https://docs.docker.com/engine/reference/commandline/logs/ docker logs]
|'''查看容器日志''' 查看容器内部的标准输出。
|<code>docker logs ubuntu-test</code>查看ubuntu-test容器内部的标准输出 <code>docker logs -f ubuntu-test</code>跟踪日志输出
|-
| docker top
|'''查看容器进程''' 查看容器内部运行的进程
| <code>docker top static_web</code> 查看static_web容器内部运行的进程
|-
| [https://docs.docker.com/engine/reference/commandline/exec/ docker exec]
|'''运行命令''' 在容器中运行命令。该命令退出容器终端，容器不会停止。
|<code>docker exec ubuntu-test ls</code>在ubuntu-test容器工作目录运行ls命令 <code>docker exec -it ubuntu-test bash</code>进入ubuntu-test容器交互式终端 <code>docker exec -u 0 -it test bash</code>以root用户进入名称为test的容器
|-
| docker attach
|'''附着终端''' 将本地终端标准输入、输出和错误流连接到运行的容器中。该命令退出容器终端，容器会停止，推荐使用<code>docker exec -it</code>。
|<code>docker attach ubuntu-test</code>
|-
|docker stop
|'''停止容器''' 停止运行中的容器
|<code>docker stop dw3342531d3</code> #停止一个id为dw3342531d3的容器 <code>docker stop $(docker ps -a -q)</code>停止所有运行中的容器
|-
|docker rm
|'''删除容器''' 删除容器，需要容器停止运行。参数-f表示强制删除，可以不用等容器停止后再删除。
|<code>docker rm ubuntu-test</code>删除ubuntu-test容器 <code>docker rm -f ubuntu-test</code>强制删除ubuntu-test容器 <code>docker rm -f $(docker ps -a -q)</code>'''注意，该命令会强制删除所有容器'''
|-
|docker container prune
|'''清理容器''' 删除所有停止的容器。
|<code>docker container prune</code>删除所有停止的容器。
|-
|docker commit
|'''容器构建镜像''' 将容器打包为一个镜像。
|<code>docker commit ubuntu-test ubuntu-updated</code>#将ubuntu-test容器打包为一个名称为ubuntu-updated镜像。
|}

== 仓库 ==
仓库（Repository）是集中存放镜像的地方。 Docker的官方镜像仓库为[https://hub.docker.com/ Docker Hub]，公共仓库为免费，私有仓库需要付费使用。

===Docker Hub===
大部分需求都可以通过在Docker Hub中直接下载镜像来实现。在[https://hub.docker.com https://hub.docker.com]免费注册一个 Docker 账号。接下来可以在终端操作
<syntaxhighlight lang="bash">
#登录使用docker login，再输入账号密码
docker login

#在Docker Hub仓库中搜索使用docker search，这命令可以不登录。
docker search ubuntu

#下载镜像使用docker pull，这命令可以不登录。
docker pull ubuntu

#上传镜像使用docker push，需要登录再使用。username为个人的账户名
docker push username/ubuntu:18.04

#退出使用docker logout
docker logout
</syntaxhighlight>
可能出现问题：
*登录时出现：Error saving credentials: error storing credentials - err: exit status 1, out: `Cannot autolaunch D-Bus without X11 $DISPLAY`
执行下面命令即可：sudo apt install gnupg2 pass

*docker push报错：denied: requested access to the resource is denied
镜像名和用户名不匹配，使用tag将镜像名改为username/镜像名，username为个人的用户名，然后再推送，如：
docker tag ubuntu:18.04 username/ubuntu:18.04
docker push username/ubuntu:18.04

===其他公有镜像仓库===
==== 常用仓库 ====
{| class="wikitable" style="width: 100%;
! 提供方
! 仓库地址
! 描述
! 网址
|-
| 阿里云
| https://xxxxxxxx.mirror.aliyuncs.com
| 需要注册阿里云，在镜像加速器可以看到仓库地址。
| [https://cr.console.aliyun.com/ 官网] [https://developer.aliyun.com/article/110806 文档]
|-
| 网易
| https://hub.c.163.com
|
| [https://sf.163.com/help/documents/56918246390157312 文档]
|-
| 百度云
| https://mirror.baidubce.com
|
|[https://cloud.baidu.com/doc/CCE/s/Yjxppt74z#如何使用dockerhub镜像加速器文档]
|-
| Google
|
|
|[https://cloud.google.com/container-registry/docs/pulling-cached-images 文档]
|}

==== 使用方法 ====
{| class="wikitable" style="width: 100%;
! 方法
! 描述
|-
| 拉取时指定仓库
| 单次有效 仓库地址不包含协议(如<code>https://</code>)，公有镜像仓库一般使用<code>library</code>。 如指定阿里镜像仓库拉取ubuntu： <code>docker pull xxxxxxxx.mirror.aliyuncs.com/library/ubuntu</code>
|-
| 编辑配置文件
| 永久有效 步骤： 1.编辑配置文件，<code>sudo vim /etc/docker/daemon.json</code>，输入如下内容<syntaxhighlight lang="json">
{
"registry-mirrors": [
"https://hub-mirror.c.163.com"
]
}
</syntaxhighlight>
2.重启docker服务，<code>sudo service docker restart</code> 3.查看是否成功，<code>docker info</code> 输出含有Registry Mirrors
|-
|
|
|}

===搭建私有镜像仓库===
<syntaxhighlight lang="bash" >
# 运行一个本地仓库
docker run -d -p 5000:5000 --restart always --name registry registry:3

# 现在，在Docker里使用，如推送，拉取
docker pull ubuntu
docker tag ubuntu localhost:5000/ubuntu
docker push localhost:5000/ubuntu
</syntaxhighlight>

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/
===镜像dockehub镜像仓库===
使用 Docker 启动 Registry 镜像加速服务
<syntaxhighlight lang="bash" >
sudo docker run -d \
--name dockerhub \
--restart=always \
-p 443:5000 \
-v /data/docker-registry:/var/lib/registry \
-v /your/domain/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.cer \
-e REGISTRY_HTTP_TLS_KEY=/certs/docker.yourdomain.com.key \
-e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
registry:3
</syntaxhighlight>

在其他电脑测试拉取镜像：
sudo docker pull yourdomain.com/library/hello-world

成功拉取后，可以配置 Docker 的默认镜像地址方便使用，没有成功查看运行日志<code>sudo docker logs dockerhub</code>。

进阶版本，使用registry + Nginx + HTTPS进行镜像加速。

*https://hub.docker.com/_/registry
*https://distribution.github.io/distribution/

==网络==
===概览===
Docker的网络是可拔插的子系统，使用驱动程序。docker内置了几个驱动程序，提供了核心网络功能。
{| class="wikitable" style="width: 100%;
! 网络模式
! 描述
! 示例
|-
| 桥接模式 [https://docs.docker.com/network/bridge/ bridge]
| bridge是默认的桥接网络，当没有指定网络驱动，新启动的容器会连接到这个名称为bridge的bridge网络。也可以自定义一个网桥，只有连接到该网络的容器才能相互通信，从而起到隔离效果。自定义的网桥可以动态的连接或断开。 创建自定义网桥：<code>docker network create 网桥名称</code> 删除自定义网桥：<code>docker network rm 网桥名称</code> 查看网桥详细信息：<code>docker network inspect 网桥名称</code> 容器启动时连接到网桥：<code>--network 网桥名称</code> 运行中的容器连接到网桥：<code>docker network connect 网桥名称容器名称</code> 断开容器与网桥：<code>docker network disconnect 网桥名称容器名称</code> 注意：默认网桥bridge的<code>--link</code>命令已不建议使用，后面版本可能会被删除。默认网桥bridge内容器只能通过ip地址通信，需要添加<code>--link</code> 来添加名称，而自定义网桥可以使用容器名称或设置别名来通信。
| <code>docker network rm my-net</code>创建自定义网桥my-net 
|-
| 主机模式 [https://docs.docker.com/network/host/ host]
| 当使用host网络模式，容器共享主机的网络命名空间，而且容器不会分配自己的 IP 地址。如果容器中某个程序绑定到端口，直接访问主机的该端口即可。该模式端口全部暴露，端口映射不生效，即-p、--publish、-P和--publish-all选项都将被忽略。主机模式网络可用于优化性能，并且在容器需要处理大量端口的情况下，因为它不需要网络地址转换 (NAT)，并且没有为每个端口创建“用户空间代理”。 容器启动时设置：<code>--network host</code>或 <code>--net=host</code>
|
|-
| 覆盖模式 [https://docs.docker.com/network/overlay/ overlay]
| 跨主机的分布式网络。该模式允许连接到它的容器（包括群服务容器）通过加密安全地通信。
|
|-
| [https://docs.docker.com/network/macvlan/ macvlan]
|
|
|-
| [https://docs.docker.com/network/ipvlan/ ipvlan]
|
|
|-
| 禁用网络 [https://docs.docker.com/network/none/ none]
| 禁用容器的网络。 容器启动时设置：<code>--network none</code>
|
|-
| 网络插件 [https://docs.docker.com/engine/extend/plugins_services/#network-plugins Network plugins]
|
|
|}

{{了解更多
|[https://docs.docker.com/network/ Docker 文档：网络概览]
}}

==数据==
===概览===
默认情况下，所有文件将会存储在容器里的可写的容器层（container layer）。意味着：
* 数据与容器为一体。当容器删除时，数据会一起被删除。
* 该容器与其他程序（容器）数据交换难。
* 由于容器的写入层是与宿主机器紧紧耦合，所以难以移动数据到其他机器。
* 容器的写入层的是通过存储驱动（storage driver）管理文件系统。存储驱动会使用Linux内核的链合文件系统（union filesystem）进行挂载。相比起直接操作于宿主机器文件系统的数据卷（data volumes），这额外的抽象层将会降低性能。

Docker提供两种将数据存储在宿主机的方法：'''数据卷（volumes）'''和 '''绑定挂载（bind mounts）'''。另外，Linux用户还可使用'''tmpfs 挂载'''；window用户还可以使用命名管道（named pipe）。可用参数 <code>-v</code> 或 <code>--mount </code>来使用数据卷或绑定挂载，一般推荐--mount，更明确和详细。

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== 数据存储类型 ===
{| class="wikitable" style="width: 100%;
! 类型
! 描述
! 示例
|-
| 数据卷 [https://docs.docker.com/storage/volumes/ volumes]
| Docker 推荐的容器数据持久化方法，volumes完全由 Docker 管理。分为命名卷和匿名卷，匿名卷在容器删除时会被 Docker 引擎删除，或者启动容器时加入--rm时，容器退出匿名卷会自动删除。 创建数据卷：<code>docker volume create 卷名称</code> 列出数据卷： <code>docker volume ls</code> 数据卷详细信息：<code>docker volume inspect 卷名称 </code> 启动容器时连接卷（不存在卷会自动创建）：<code>--mount source=卷名称,target=/容器的/目录</code> 或 <code>-v 卷名称:/容器的/目录 </code> 启动容器时连接匿名卷：<code>-v /容器的/目录</code> 删除卷：<code>docker volume rm 卷名称</code> 清理没有使用的卷：<code>docker volume prune</code>
|
|-
| 绑定挂载 [https://docs.docker.com/storage/bind-mounts/ bind mounts]
| 将主机上的文件或目录挂载到容器中。主机的路径可以是相对路径。 启动容器时绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录</code> 或 <code>-v 主机/目录:/容器/目录</code> 只读绑定挂载：<code>--mount type=bind,source=主机/目录,target=/容器/目录,readonly</code> 或 <code>-v 主机/目录:/容器/目录:ro</code>
|
|-
|tmpfs 挂载 [https://docs.docker.com/storage/tmpfs/ tmpfs mounts]
|tmpfs挂载是临时的，仅保留在主机内存中。当容器停止时，tmpfs挂载被移除，写入的文件不会被持久化。这对于临时存储您不想保留在主机或容器可写层中的敏感文件很有用。 可用命令 <code>-tmpfs </code> 或 <code>--mount </code>
|
|}

{{了解更多
|[https://docs.docker.com/storage/ Docker 文档：Docker上管理数据]
}}

=== -v和--mount 参数 ===
使用命令 <code>docker inspect 容器名称</code> 可以查看容器详情，其中Mounts部分可以看到容器的挂载详细情况。
{| class="wikitable" style="width: 100%;
! 参数
! -v 或 --volume
! --mount
|-
! 特点
| 简洁，但有时出现混乱。
| 类型指定明确，推荐写法。
|-
! 支持类型
| <code>volumes</code>、<code>bind mounts</code>
| <code>volumes</code>、<code>bind mounts</code>、<code>tmpfs</code>
|-
! volumes
| <code>-v 卷名称:/容器的/目录 </code>
| <code>--mount source=卷名称,target=/容器的/目录</code>
|-
! bind mounts
| <code>-v 主机/目录:/容器/目录</code>
| <code>--mount type=bind,source=主机/目录,target=/容器/目录</code>
|-
! tmpfs mounts
| 不支持
| <code>--mount type=tmpfs,destination=/app</code>
|}
{{了解更多
|[https://docs.docker.com/storage/volumes/ Docker 文档：Use volumes]
|[https://docs.docker.com/storage/bind-mounts/ Docker 文档：Use bind mounts]
|[https://docs.docker.com/storage/tmpfs/ Docker 文档：Use tmpfs mounts]
}}
== 命令行 ==
{| class="wikitable"
! 名称
! 描述
! 示例
|-
|
|
|
|-
|
|
|
|-
|[https://docs.docker.com/engine/reference/commandline/system/ docker system]
| 管理docker 。如使用docker system prune能清理docker占用的磁盘空间，包括不使用的空间，构建镜像时的缓存等。
| docker system prune -a
|}

{{了解更多
|[https://docs.docker.com/engine/reference/commandline/cli/ Docker 文档：使用 Docker 命令行]
}}

==Compose==
Docker Compose 是用于定义和运行多容器 Docker 应用程序的工具。通过 Compose，您可以使用[[YML]]文件来配置应用程序需要的所有服务。然后，使用一个命令，就可以从[[YML]]文件配置中创建并启动所有服务。
=== 安装===
====版本====
{| class="wikitable"
! 名称
! 命令
! 描述
|-
| Compose 旧版
| docker-compose
| Compose 旧版为独立版，下载可执行文件使用。
|-
| Compose V2
| docker compose
| Compose V2也叫Compose插件版，作为插件和docker集成，安装升级方便。新版也提供更多的功能。
|}

{{了解更多
|[https://docs.docker.com/compose/ Docker Compose 文档]
}}

====Compose V2安装====
<syntaxhighlight lang="bash" >
# Ubuntu and Debian 安装
sudo apt-get update
sudo apt-get install docker-compose-plugin

# RPM-based distros 安装
sudo yum update
sudo yum install docker-compose-plugin

</syntaxhighlight>
{{了解更多
|[https://docs.docker.com/compose/install/ Docker 文档：安装Docker Compose]
}}
====Compose 旧版安装====
以Linux系统为例，使用<code>curl</code>命令在终端从GitHub上下载[https://github.com/docker/compose/releases Docker Compose]二进制文件。
<syntaxhighlight lang="bash" line='line'>
# 查看系统类型
echo $(uname -s)-$(uname -m)

# GitHub上右键复制系统对应版本，如linux-x86_64。如下载当前最新版compose 2.2.2
sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.2/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose

# 为compose程序文件添加执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 查看compose版本，验证是否安装成功
docker-compose --version
</syntaxhighlight>

{{了解更多
|[https://docs.docker.com/compose/install/other/ Docker 文档：安装 Compose 独立版]
}}

=== 快速入门 ===

===Compose 命令===
进入<code>docker-compose.yml</code>配置文件所在目录，执再行命令。
常用选项：
* -f, --file 指定其他名称配置文件。如：<code>docker compose -f docker-compose.prod.yml up</code>
*-p, --project-name 制定项目名称。如：<code>docker compose -p myproject up</code>

Compose 常用命令：
{| class="wikitable"
! 命令
! 描述
! 示例
|-
| [https://docs.docker.com/engine/reference/commandline/compose_up/ up]
| 自动执行一些列操作：构建镜像、创建服务、启动服务和关联服务相关容器。
| <code>docker compose up</code> <code>docker compose up -d</code> <code>docker compose -f docker-compose.dev.yml up --build </code>
|-
| stop
|
|
|-
| logs
|
| <code>logs</code>默认以不同颜色显示服务内容器的日志。
|-
| config
| 显示 Docker Compose 配置，包括环境变量。
| <code>docker compose config</code> 查看当前目录docker-compose.yml配置 <code>docker-compose -f docker-compose.dev.yml config</code> 查看当前docker-compose.dev.yml配置
|-
|
|
|
|-
| rm
|
| <code>docker compose rm -f</code> 强制删除服务内容器。 <code>docker rm -f $(docker compose ps -a -q)</code> 删除服务内所有容器。
|-
|
|
|
|}

{{了解更多
|[https://docs.docker.com/compose/reference/ Docker 文档：docker compose CLI ]
}}

==Swarm Mode==
Swarm Mode是Docker集群管理工具，从Docker1.2开始Docker Swarm内置到Docker中为Swarm Mode。

{{了解更多
|[https://docs.docker.com/engine/swarm/ Docker文档-Swarm mode]
}}
==安全==

==国内加速==
=== Docker CE镜像 ===
用于安装docker社区版软件。
{| class="wikitable"
! 名称
! 描述
|-
| 中国科学技术大学 USTC
| 手动安装时把 download.docker.com 地址换成 mirrors.ustc.edu.cn/docker-ce 即可。 地址：https://mirrors.ustc.edu.cn/docker-ce/ 文档：https://mirrors.ustc.edu.cn/help/docker-ce.html
|-
|
|
|-
|
|
|}
=== Docker Hub镜像 ===

=== 周边加速 ===
{| class="wikitable"
! 名称
! 描述
|-
| Dockerfile中apt更换软件源
| Debian换阿里源： <code>RUN sed -i s@/deb.debian.org/@/mirrors.aliyun.com/@g /etc/apt/sources.list</code>
|-
| Github镜像网站
| kgithub.com ：将Dockerfile中的github.com换成kgithub.com
|-
| 设置DNS
| echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf > /dev/null
|}

==实例==
====Docker安装Nginx====

====Docker安装Flask====
[[Flask]]是一个使用[[Python]]编写的轻量级Web应用框架。下面使用Dockerfile生成一个简单flask镜像，并启动。
<syntaxhighlight lang="bash">
#创建一个文件夹来保存项目
mkdir hello_flask
#利用 cd 命令切换到这个目录
cd hello_flask
</syntaxhighlight>接下来使用vim app.py命令创建一个app.py文件，内容如下：
<syntaxhighlight lang="python">
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
return 'Hello, World!'

if __name__=='__main__':
app.run(debug=True, host='0.0.0.0')
</syntaxhighlight>然后使用vim Dockerfile命令创建一个Dockerfile文件，内容如下：
<syntaxhighlight lang="bash">
app = Flask(__name__)

FROM python:alpine

COPY . /app
WORKDIR /app

RUN pip install Flask

ENTRYPOINT ["python"]
CMD ["app.py"]
</syntaxhighlight>现在hello_flask文件夹下有两个文件app.py和Dockerfile，
<syntaxhighlight lang="bash">
#在hello_flask文件夹下使用docker build命令生成镜像
docker build -t flask:1.1.1-min .

#使用 docker run 命令运行刚刚创建的镜像：
docker run --name flask -d -p 8080:5000 flask:1.1.1-min
</syntaxhighlight>
现在在浏览器打开ip;10000,可以看到Hello, World!

可以使用-v命令，把当前路径挂载到容器的/app目录，$PWD表示当前目录，比如现在的hello_flask。
docker run --name flask2 -d -p 8080:5000 -v $PWD:/app flask:1.1.1-min
在浏览器打开ip:8080可以看到“Hello, World!”，挂载后在主机中的hello_flask修改app.py，刷新网页就会看到更新的内容。修改文件时候要使用root权限不然会报错，sudo vim app.py

====Docker安装Mediawiki====
[[Mediawiki]]全球最著名的开源wiki程序，维基百科也使用该软件。

方法一：利用Docker Hub上现成镜像
<syntaxhighlight lang="bash">
#运行mediawiki镜像，没有就从docker hub下载mediawiki再运行
docker run --name some-mediawiki -p 8080:80 -d mediawiki

</syntaxhighlight>{{了解更多
|[https://hub.docker.com/_/mediawiki Docker Hub：Mediawiki ]
}}

==资源==
===官网===
*Docker 官网：https://www.docker.com
*Docker Hub：https://hub.docker.com/
*Docker 文档：https://docs.docker.com
*Docker 文档 > 参考：https://docs.docker.com/reference
*Docker 文档 > 示例：https://docs.docker.com/samples
*Docker CE 的 Github：https://github.com/docker/docker-ce

===相关网页===
*[https://zh.wikipedia.org/wiki/Docker 维基百科：Docker]
*[https://zh.wikipedia.org/wiki/操作系统层虚拟化维基百科：操作系统层虚拟化]

[[分类:编程工具]]

智能音箱

2026-04-15T16:18:12Z

Eric：/* 文本转语音 */

智能音箱是一种内置语音助手的智能音响，可以接收语音指令，进行播放音乐、对话问答，控制家庭设备等。

==简介==
===时间轴===

==常见产品==
{| class="wikitable"
! 产品
! 虚拟助手
! 公司
! 描述
|-
| 天猫精灵
| [https://www.aligenie.com/ AliGenie]
| 阿里巴巴
|
|-
| 小度
| [https://dueros.baidu.com/open DuerOS]
| 百度
|
|-
| 小爱同学
| [https://developers.xiaoai.mi.com/ 小爱同学]
| 小米
|
|-
|
|
|
|
|-
| Echo
| [https://www.alexa.com/ Alexa]
| 亚马逊
|
|-
| HomePod
| Siri
| 苹果
|
|-
|
|
|
|
|}

== 硬件 ==

== 技术 ==
=== 语音前端处理 ===
语音前端处理（Audio Processing）

=== 唤醒 ===
唤醒，也称Keyword Spotting (KWS)，即关键词检测。当录音识别到关键词（如设置'天猫精灵'，'hey Siri'），就开始录制后面的语音，进行分析处理。
{| class="wikitable"
! 名称
! 描述
|-
| [[microWakeWord]]
| 开源唤醒词引擎，支持低功耗设备如esp32。https://github.com/OHF-Voice/micro-wake-word
|-
| [[openWakeWord]]
| 开源唤醒词引擎。 https://github.com/dscripka/openWakeWord
|-
| [[Picovoice#Porcupine | Porcupine]]
| 是一款离线轻量级的唤醒词引擎，支持多语言，多平台。免费账号每个月只支持3个用户和3个唤醒词训练。
|-
| SnowBoy
|
|-
| 讯飞语音唤醒
| 免费版10个用户90天试用期。 官网：https://www.xfyun.cn/service/awaken?type=awaken
|-
|
|
|}

===语音转文本===
语音识别（Automatic Speech Recognition, ASR），也称语音转文本（Speech To Text，STT）。
{| class="wikitable"
! 名称
! 开发者
! 描述
|-
| whisper
| OpenAI
| 是OpenAI在2022年9月开源的语音识别（ASR）软件。可以用于本地离线识别，或安装在服务器上提供API。 支持语言：中文、英语、法语、德语、俄语、日语等几十种语言。 价格：免费。 官网：https://openai.com/index/whisper/ 源代码：https://github.com/openai/whisper
|-
|OpenAI 语音识别API
| OpenAI
| 基于开源 large-v2 Whisper 模型。 支持语言：中文、英语、法语、德语、俄语、日语等几十种语言。 价格：收费 官网：https://platform.openai.com/docs/guides/speech-to-text/speech-to-text
|-
| PaddleSpeech
| 百度
| 百度开源的语音方向的开源模型库，基于百度飞桨 PaddlePaddle。支持声音分类、语音识别（ASR）、语音翻译（英译中）、语音合成（TTS）和声纹验证。 支持语言： 源代码：https://github.com/PaddlePaddle/PaddleSpeech
|-
|
|
|
|-
|
|
|
|-
|
|
|
|}

===自然语言理解===
自然语言理解 (Natural Language Understanding, NLU)

===文本转语音===
文本转语音（TTS），也称语音合成。

==项目==
{| class="wikitable"
! 名称
! 描述
|-
| Mycroft
| https://github.com/MycroftAI/mycroft-core
|-
| wukong-robot
| 是一个开源的中文语音对话机器人/智能音箱项目。 https://wukong.hahack.com/
|-
|
|
|}

==资源==
===网站===

===文章===
*[https://github.com/voice-engine/make-a-smart-speaker/blob/master/zh.md Github：voice-engine/make-a-smart-speaker DIY智能音箱]

智能音箱

2026-04-15T13:51:20Z

Eric：/* 唤醒 */

智能音箱是一种内置语音助手的智能音响，可以接收语音指令，进行播放音乐、对话问答，控制家庭设备等。

==简介==
===时间轴===

==常见产品==
{| class="wikitable"
! 产品
! 虚拟助手
! 公司
! 描述
|-
| 天猫精灵
| [https://www.aligenie.com/ AliGenie]
| 阿里巴巴
|
|-
| 小度
| [https://dueros.baidu.com/open DuerOS]
| 百度
|
|-
| 小爱同学
| [https://developers.xiaoai.mi.com/ 小爱同学]
| 小米
|
|-
|
|
|
|
|-
| Echo
| [https://www.alexa.com/ Alexa]
| 亚马逊
|
|-
| HomePod
| Siri
| 苹果
|
|-
|
|
|
|
|}

== 硬件 ==

== 技术 ==
=== 语音前端处理 ===
语音前端处理（Audio Processing）

=== 唤醒 ===
唤醒，也称Keyword Spotting (KWS)，即关键词检测。当录音识别到关键词（如设置'天猫精灵'，'hey Siri'），就开始录制后面的语音，进行分析处理。
{| class="wikitable"
! 名称
! 描述
|-
| [[microWakeWord]]
| 开源唤醒词引擎，支持低功耗设备如esp32。https://github.com/OHF-Voice/micro-wake-word
|-
| [[openWakeWord]]
| 开源唤醒词引擎。 https://github.com/dscripka/openWakeWord
|-
| [[Picovoice#Porcupine | Porcupine]]
| 是一款离线轻量级的唤醒词引擎，支持多语言，多平台。免费账号每个月只支持3个用户和3个唤醒词训练。
|-
| SnowBoy
|
|-
| 讯飞语音唤醒
| 免费版10个用户90天试用期。 官网：https://www.xfyun.cn/service/awaken?type=awaken
|-
|
|
|}

===语音转文本===
语音识别（Automatic Speech Recognition, ASR），也称语音转文本（Speech To Text，STT）。
{| class="wikitable"
! 名称
! 开发者
! 描述
|-
| whisper
| OpenAI
| 是OpenAI在2022年9月开源的语音识别（ASR）软件。可以用于本地离线识别，或安装在服务器上提供API。 支持语言：中文、英语、法语、德语、俄语、日语等几十种语言。 价格：免费。 官网：https://openai.com/index/whisper/ 源代码：https://github.com/openai/whisper
|-
|OpenAI 语音识别API
| OpenAI
| 基于开源 large-v2 Whisper 模型。 支持语言：中文、英语、法语、德语、俄语、日语等几十种语言。 价格：收费 官网：https://platform.openai.com/docs/guides/speech-to-text/speech-to-text
|-
| PaddleSpeech
| 百度
| 百度开源的语音方向的开源模型库，基于百度飞桨 PaddlePaddle。支持声音分类、语音识别（ASR）、语音翻译（英译中）、语音合成（TTS）和声纹验证。 支持语言： 源代码：https://github.com/PaddlePaddle/PaddleSpeech
|-
|
|
|
|-
|
|
|
|-
|
|
|
|}

===自然语言理解===
自然语言理解 (Natural Language Understanding, NLU)

===文本转语音===
语音合成，

==项目==
{| class="wikitable"
! 名称
! 描述
|-
| Mycroft
| https://github.com/MycroftAI/mycroft-core
|-
| wukong-robot
| 是一个开源的中文语音对话机器人/智能音箱项目。 https://wukong.hahack.com/
|-
|
|
|}

==资源==
===网站===

===文章===
*[https://github.com/voice-engine/make-a-smart-speaker/blob/master/zh.md Github：voice-engine/make-a-smart-speaker DIY智能音箱]

OpenCode

2026-04-13T06:18:39Z

Eric：

OpenCode是一个开源的AI代理编程工具。

==简介==
===时间轴===

==安装==
=== 使用脚本安装 ===
curl -fsSL https://opencode.ai/install | bash

=== 使用包管理器安装 ===
# 安装 Node.js，[[npm]]包含在其中。https://nodejs.org/zh-cn/download
# 使用[[npm]]安装opencode。 npm install -g opencode-ai

安装完成后，运行 opencode --version 验证是否成功

*https://opencode.ai/docs#install
*https://opencode.ai/download
*https://github.com/anomalyco/opencode/releases

==快速入门==
* 终端配置：opencode auth login
* 会提示选择一个模型，输入API KEY

==指令==
===内置指令===

===自定义指令===

==技能==

==资源==
===官网===
*opencode官网： https://opencode.ai/
*opencode源码： https://github.com/anomalyco/opencode

===网站===

树莓派

2026-04-04T04:47:03Z

Eric：/* Python */

树莓派（Raspberry Pi）

==简介==
===时间轴===
* 2023年10月10日，发布的Bookworm树莓派操作系统。

{{了解更多
|[https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/ 树莓派News：新树莓派操作系统版本bookworm ]
}}
===安装===
树莓派5，NVMe固态硬盘安装树莓派系统。

方法一：使用U盘连接到电脑写入系统，再插入树莓派安装，安装后使用dd复制到固态硬盘，调整硬盘大小。移除U盘。

方法二：将固态硬盘连接到电脑写入系统，再插入树莓派安装。

==软件==
安装中文输入法，以Google拼音输入法示例。
<syntaxhighlight lang="bash" >
sudo apt udpate
sudo apt install fcitx fcitx-googlepinyin

# 安装后重启
sudo reboot
</syntaxhighlight>
添加Google拼音，点击树莓派图标 -> Preference -> Fcitx Configuration，添加Google Pinyin 谷歌拼音输入法。可以使用<code>Ctrl + 空格</code>来切换输入法。

==常见问题==
* 任务栏消失了。
为了匹配树莓派5硬件，树莓派新版操作系统，基于Debian 12 “Bookworm”。现在使用wf-panel-pi应用程序管理系统面板，删除用户目录下.config目录中的wf-panel-pi所有文件即可重置。在终端输入：<code>rm -rf ~/.config/wf-panel-pi.ini*</code>

==GPIO==

===Python===
使用[[Python]]语言编程，可以使用默认安装在树莓派系统的[[gpiozero]]库，是一个开源的树莓派GPIO设备接口库，简单易用。

以下示例将一个LED灯串联电阻后接到最后两个引脚Pin39（GND），Pin40（GPIO21），使其闪烁。
<syntaxhighlight lang="python" >
from gpiozero import LED
from time import sleep

led = LED(21)

while True:
led.on()
sleep(1)
led.off()
sleep(1)
</syntaxhighlight>

在Python虚拟环境(venv)中运行程序，使用pip安装gpiozero后使用GPIO出现问题<code>gpiozero.exc.BadPinFactory: Unable to load any default pin factory!</code>，可以修改venv配置文件<code>pyvenv.cfg</code>内容<code>include-system-site-packages = true</code>，其默认值为false，然后重新运行程序即可。

灯还是不亮，看看是不是引脚图看错方向了，pin02(5V供电)是在板子的角落。

{{了解更多
|[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html 树莓派文档：树莓派硬件]
|[https://projects.raspberrypi.org/en/projects/physical-computing/0 树莓派项目：使用Python物理计算]
|[https://github.com/gpiozero/gpiozero/ GitHub：gpiozero/gpiozero]
|[https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi Adafruit.com：树莓派上使用Python虚拟环境]
}}

==远程连接==
=== SSH ===

=== VNC远程桌面 ===
* 开启树莓派VNC服务
<syntaxhighlight lang="bash" >
sudo raspi-config
# 选择Interfacing Options -> VNC -> Yes -> Finish

sudo reboot
</syntaxhighlight>

* 连接网络，查看IP地址
<syntaxhighlight lang="bash" >
ifconfig
</syntaxhighlight>

* 远程主机安装VNC客户端，如RealVNC或TigerVNC。
* 打开VNC客户端，输入树莓派IP地址连接。

=== RDP远程桌面 ===
* 树莓派上安装 xrdp
<syntaxhighlight lang="bash" >
sudo apt-get install xrdp
</syntaxhighlight>

* 在 Windows 上使用内置的远程桌面连接工具

==资源==
===官网===
*树莓派官网：https://www.raspberrypi.org/

===网站===
*树莓派Pinout：https://pinout.vvzero.com/
===文章===

树莓派

2026-04-04T04:35:53Z

Eric：

树莓派（Raspberry Pi）

==简介==
===时间轴===
* 2023年10月10日，发布的Bookworm树莓派操作系统。

{{了解更多
|[https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/ 树莓派News：新树莓派操作系统版本bookworm ]
}}
===安装===
树莓派5，NVMe固态硬盘安装树莓派系统。

方法一：使用U盘连接到电脑写入系统，再插入树莓派安装，安装后使用dd复制到固态硬盘，调整硬盘大小。移除U盘。

方法二：将固态硬盘连接到电脑写入系统，再插入树莓派安装。

==软件==
安装中文输入法，以Google拼音输入法示例。
<syntaxhighlight lang="bash" >
sudo apt udpate
sudo apt install fcitx fcitx-googlepinyin

# 安装后重启
sudo reboot
</syntaxhighlight>
添加Google拼音，点击树莓派图标 -> Preference -> Fcitx Configuration，添加Google Pinyin 谷歌拼音输入法。可以使用<code>Ctrl + 空格</code>来切换输入法。

==常见问题==
* 任务栏消失了。
为了匹配树莓派5硬件，树莓派新版操作系统，基于Debian 12 “Bookworm”。现在使用wf-panel-pi应用程序管理系统面板，删除用户目录下.config目录中的wf-panel-pi所有文件即可重置。在终端输入：<code>rm -rf ~/.config/wf-panel-pi.ini*</code>

==GPIO==

===Python===
使用[[Python]]语言编程，可以使用默认安装在树莓派系统的[[gpiozero]]库，是一个开源的树莓派GPIO设备接口库，简单易用。

以下示例将一个LED灯串联电阻后接到最后两个引脚Pin39（GND），Pin40（GPIO21），使其闪烁。
<syntaxhighlight lang="python" >
from gpiozero import LED
from time import sleep

led = LED(21)

while True:
led.on()
sleep(1)
led.off()
sleep(1)
</syntaxhighlight>

在Python虚拟环境(venv)中运行程序，使用pip安装gpiozero后使用GPIO出现问题<code>gpiozero.exc.BadPinFactory: Unable to load any default pin factory!</code>，可以修改venv配置文件<code>pyvenv.cfg</code>内容<code>include-system-site-packages = true</code>，其默认值为false，然后重新运行程序即可。

{{了解更多
|[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html 树莓派文档：树莓派硬件]
|[https://projects.raspberrypi.org/en/projects/physical-computing/0 树莓派项目：使用Python物理计算]
|[https://github.com/gpiozero/gpiozero/ GitHub：gpiozero/gpiozero]
|[https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi Adafruit.com：树莓派上使用Python虚拟环境]
}}

==远程连接==
=== SSH ===

=== VNC远程桌面 ===
* 开启树莓派VNC服务
<syntaxhighlight lang="bash" >
sudo raspi-config
# 选择Interfacing Options -> VNC -> Yes -> Finish

sudo reboot
</syntaxhighlight>

* 连接网络，查看IP地址
<syntaxhighlight lang="bash" >
ifconfig
</syntaxhighlight>

* 远程主机安装VNC客户端，如RealVNC或TigerVNC。
* 打开VNC客户端，输入树莓派IP地址连接。

=== RDP远程桌面 ===
* 树莓派上安装 xrdp
<syntaxhighlight lang="bash" >
sudo apt-get install xrdp
</syntaxhighlight>

* 在 Windows 上使用内置的远程桌面连接工具

==资源==
===官网===
*树莓派官网：https://www.raspberrypi.org/

===网站===
*树莓派Pinout：https://pinout.vvzero.com/
===文章===

CadQuery

2026-04-02T02:30:26Z

Eric：/* 3D 操作（无需活动工作平面） */

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane初始化及其他 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|-
| <code>Workplane.tag(name)</code> || 为当前栈顶对象添加标签，便于后续引用 || <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code> 为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面 <code>cq.Workplane("XY").polygon(3, 5).extrude(4).tag("prism").sphere(10).faces("<X", tag="prism").workplane().circle(1).cutThruAll()</code> Tags也可以与大多数选择器一起使用。
|-
| <code>Workplane.workplaneFromTagged(tag)</code> || 从之前标记的标签恢复/复制工作平面 || <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code> 从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）
|-
| <code>Workplane.copyWorkplane(other)</code> || 复制另一个 Workplane 的平面信息到当前对象 || <code>new_wp = cq.Workplane().copyWorkplane(other_wp)</code> 创建新的工作平面，并将另一个工作平面 other_wp 的坐标系信息复制到新对象上
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形。 <code>cq.Workplane().box(4, 2, 0.5).faces(">Z").edges().toPending().offset2D(-0.25, forConstruction=True).vertices().cboreHole(0.125, 0.25, 0.125, depth=None)</code> 在顶面向里偏离0.25，再在四个顶点打螺栓孔。

|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体 <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code> 

|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|-
| <code>Workplane.split(plane[, keepTop, keepBottom])</code> || 将栈上的实体按平面或分割器分割成两部分，可选择保留顶部、底部或两者。 || <code>result = cq.Workplane().box(50, 50, 50).faces(">Y").workplane(-10).split(keepTop=True)</code> 使用工作平面将盒子沿 Y 方向在偏移 -10 的位置分割，只保留上半部分。<code>keepTop=True</code> 保留法线方向一侧，<code>keepBottom=True</code> 保留另一侧，<code>keepBoth=True</code> 同时保留两部分并返回元组
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T02:25:04Z

Eric：/* Workplane初始化及其他 */

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane初始化及其他 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|-
| <code>Workplane.tag(name)</code> || 为当前栈顶对象添加标签，便于后续引用 || <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code> 为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面 <code>cq.Workplane("XY").polygon(3, 5).extrude(4).tag("prism").sphere(10).faces("<X", tag="prism").workplane().circle(1).cutThruAll()</code> Tags也可以与大多数选择器一起使用。
|-
| <code>Workplane.workplaneFromTagged(tag)</code> || 从之前标记的标签恢复/复制工作平面 || <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code> 从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）
|-
| <code>Workplane.copyWorkplane(other)</code> || 复制另一个 Workplane 的平面信息到当前对象 || <code>new_wp = cq.Workplane().copyWorkplane(other_wp)</code> 创建新的工作平面，并将另一个工作平面 other_wp 的坐标系信息复制到新对象上
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形。 <code>cq.Workplane().box(4, 2, 0.5).faces(">Z").edges().toPending().offset2D(-0.25, forConstruction=True).vertices().cboreHole(0.125, 0.25, 0.125, depth=None)</code> 在顶面向里偏离0.25，再在四个顶点打螺栓孔。

|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体 <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code> 

|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T02:18:14Z

Eric：/* Workplane 初始化 */

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane初始化及其他 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|-
| <code>Workplane.tag(name)</code> || 为当前栈顶对象添加标签，便于后续引用 || <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code> 为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面
|-
| <code>Workplane.workplaneFromTagged(tag)</code> || 从之前标记的标签恢复/复制工作平面 || <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code> 从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）
|-
| <code>Workplane.copyWorkplane(other)</code> || 复制另一个 Workplane 的平面信息到当前对象 || <code>new_wp = cq.Workplane().copyWorkplane(other_wp)</code> 创建新的工作平面，并将另一个工作平面 other_wp 的坐标系信息复制到新对象上
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形。 <code>cq.Workplane().box(4, 2, 0.5).faces(">Z").edges().toPending().offset2D(-0.25, forConstruction=True).vertices().cboreHole(0.125, 0.25, 0.125, depth=None)</code> 在顶面向里偏离0.25，再在四个顶点打螺栓孔。

|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体 <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code> 

|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T02:07:10Z

Eric：/* 2D 操作 */

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane 初始化 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形。 <code>cq.Workplane().box(4, 2, 0.5).faces(">Z").edges().toPending().offset2D(-0.25, forConstruction=True).vertices().cboreHole(0.125, 0.25, 0.125, depth=None)</code> 在顶面向里偏离0.25，再在四个顶点打螺栓孔。

|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体 <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code> 

|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T01:51:22Z

Eric：/* 3D 操作（需要活动工作平面） */

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane 初始化 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形
|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体 <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code> 

|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T01:30:59Z

Eric：

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>
如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane 初始化 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形
|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体
|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===

CadQuery

2026-04-02T01:15:12Z

Eric：

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==安装==
最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
===CQ-Editor===
安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
pip install CQ-editor
安装后，通过命令行启动：
CQ-editor

https://github.com/CadQuery/CQ-editor/wiki/Installation

===VS Code===
VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
pip install cadquery
安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
<syntaxhighlight lang="python" >
import cadquery as cq
from ocp_vscode import show, show_object

result = cq.Workplane("XY").box(2,2,2).shell(0.2)
show_object(result)
</syntaxhighlight>

https://cadquery.readthedocs.io/en/latest/installation.html
https://github.com/bernhard-42/vscode-ocp-cad-viewer
==快速入门==

== 核心概念 ==
CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

=== BREP 拓扑 ===
CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

* '''顶点 (Vertex)'''：空间中的一个点
* '''边 (Edge)'''：连接两个或多个顶点的曲线段
* '''线框 (Wire)'''：一组相互连接的边
* '''面 (Face)'''：由线框围成的平面或曲面
* '''实体 (Solid)'''：由面围成的封闭三维体
* '''复合体 (Compound)'''：多个实体的集合

=== API 层次结构 ===
CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
==== 流畅 API ====
流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
<syntaxhighlight lang="python" >
# 创建一个带孔和圆角的平板
sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

# 在底板上表面画圆孔
hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
</syntaxhighlight>

Sketch 和 Workplane 的 2D 操作区别：
*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

==== 直接 API ====
* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
* 可以“自底向上”构建几何体，控制更精细。
* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

==== OCCT API ====
* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
* 极其强大但也极其繁琐，适合需要完全控制的场景。
* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

=== 在 API 之间切换 ===
你可以根据需要混合使用不同层次的 API：

* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

=== 选择器 ===
选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code> 创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code> 从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code> 初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code> 完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code> 创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code> 创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code> 将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code> 创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code> 选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code> 清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code> 创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code> 选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code> 选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code> 选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code> 从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code> 创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code> 创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code> 创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code> 创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code> 绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code> 创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code> 创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code> 创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code> 创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code> 沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code> 在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code> 将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code> 创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code> 创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code> 创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code> 清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code> 添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code> 从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code> 通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code> 绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code> 添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code> 创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code> 创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code> 添加重合约束后求解，更新几何位置
|}
=== Workplane 初始化 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code> 创建一个新的Workplane对象，默认在XY平面原点。
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code> 将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code> 从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code> 从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code> 从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code> 垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code> 水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code> 水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code> 以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code> 绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code> 将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code> 相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code> 绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code> 绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code> 绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code> 从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code> 绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code> 绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code> 先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code> 将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code> 将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code> 将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code> 在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code> 在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code> 在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code> 在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code> 绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code> 闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code> 创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code> 创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.slot2D(length, diameter[, angle])</code> || 创建带圆角的槽形 || <code>cq.Workplane().slot2D(20, 5)</code> 在工作平面原点创建长度 20、宽度 5 的跑道形槽
|-
| <code>Workplane.offset2D(d[, kind, forConstruction])</code> || 创建 2D 偏移线框 || <code>cq.Workplane().rect(10, 10).offset2D(2)</code> 将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形
|-
| <code>Workplane.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code> 将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code> 在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code> 在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <code>Workplane.hole(diameter[, depth, clean])</code> || 创建通孔或盲孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code> 在盒子顶面上创建直径 5、深度 8 的盲孔
|-
| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> || 将线框挤出为棱柱体 || <code>result = cq.Workplane().rect(10, 20).extrude(30)</code> 将 10x20 矩形沿法线方向挤出高度 30 的实体
|-
| <code>Workplane.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code> 从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code> 将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code> 将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code> 创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code> 在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code> 创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code> 创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code> 将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code> 将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code> 创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code> 将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)]) result = cq.Workplane().circle(2).sweep(path)</code> 沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code> 将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code> 将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code> 创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code> 创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code> 在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code> 在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code> 绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code> 创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code> 将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code> 创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code> 在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code> 在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code> 获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code> 获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code> 获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code> 创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code> 获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code> 获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code> 获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code> 获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code> 从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code> 选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code> 选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code> 选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code> 选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code> 选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code> 创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code> 合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code> 选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code> 选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code> 选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code> 选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code> 选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code> 选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code> 选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code> 选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code> 选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code> 选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code> 选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code> 选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code> 按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code> 选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code> 选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code> 选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code> 使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code> 创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base") assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code> 向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code> 将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code> 约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code> 求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0) assy.add(part, color=red)</code> 创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code> 创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code> 创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code> 从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code> 从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code> 将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument() doc.addShape(sketch) doc.save("output.dxf")</code> 创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===