企业官网建设流程全解析

• 开发工具
• IDE
• 代码编辑器

Spyder（Scientific Python Development Environment）为科学计算场景提供了编辑器、控制台、变量浏览器等一整套开发设施。本文以仓库内随 Spyder 一起分发的内置教程 tutorial.rst 为骨架，系统讲解如何用 Spyder 运行程序、在 IPython 控制台与命名空间之间高效协作、配置运行与风格检查、掌握快捷键、编写规范的 docstring，并完成断点调试与 Matplotlib 绘图。读完本文，你将获得一份可直接照做的 Spyder 上手与进阶路线图，同时理解这些操作在 Spyder 源码与 spyder-kernels 内核中的真实实现。

教程从哪里来：内置教程的加载与渲染机制

这份教程不是独立的在线文档，而是随 Spyder 打包、在 Help 面板中动态渲染的交互式内容。在 Help 面板（默认位于窗口右上角）的 Usage 页，你会看到"New to Spyder? Read our tutorial"的入口，点击后会通过spy://tutorial这个内置 URL 触发加载，相关实现位于 plugin.py 与 widgets.py：

• show_tutorial()使用get_module_source_path('spyder.plugins.help.utils')定位到utils目录，读取其中的tutorial.rst源文件；
• 同时把utils/static/images作为图片目录传入渲染上下文，因此教程中引用的截图（如images/spyder-hello-docstring.png）会被正确解析；
• 最终内容交给基于 Sphinx 的渲染管线处理：Sphinx 配置见 conf.py，渲染过程封装在 sphinxify.py 中。

值得一提的细节是，conf.py 会根据用户在偏好中是否启用数学公式渲染，动态决定挂载sphinx.ext.jsmath还是sphinx.ext.mathjax扩展，并通过mathjax_path = 'MathJax/MathJax.js'指向仓库内自带的 MathJax（位于utils/js/mathjax）。这就是你在帮助面板中看到 LaTeX 风格数学公式渲染的底层支撑。

如果你是 Python 与 Spyder 的初学者，从下一节开始逐步操作；若已熟悉基本用法，可直接跳到快捷键、运行配置或调试章节。

第一步：在 Spyder 中运行你的第一个程序

编写并运行 hello.py

先在 Spyder 的**编辑器（Editor）**窗格中新建文件（菜单File --> New file，或快捷键Ctrl-N/Command-N），粘贴以下代码并保存为hello.py：

# Demo file for Spyder Tutorial # Hans Fangohr, University of Southampton, UK def hello(): """Print "Hello World" and return None.""" print("Hello World") # Main program starts here hello()

然后选择菜单Run --> Run（或按F5）执行，首次运行时如果弹出Run settings对话框，确认即可。程序会在IPython 控制台（默认位于右下角）中执行，你应该看到类似输出：

In [1]: %runfile '/File/Path/hello.py' --wdir Hello World In [2]:

这里%runfile后面的具体路径取决于你保存文件的位置，它是 Spyder 自动插入的。恭喜，你刚刚完成了第一个 Spyder 程序的运行。

执行时到底发生了什么

Python 解释器对hello.py的处理过程如下：

1. 逐行读取文件，忽略以#开头的注释行；
2. 遇到def关键字时，知道此处正在定义函数——def hello():之后所有缩进的行都属于函数体。注意：此时只是创建了函数对象，函数并未被调用；
3. 当解释器遇到写在最左列的普通命令（非def等关键字）时，会立即执行；
4. 在hello.py中，这一行就是hello()，它真正调用（执行）了名为hello的函数。

如果注释或删除hello()这一行，再按F5运行整个文件，将不会有任何输出——因为函数被定义但没有被调用。

源码视角：%runfile 是什么

教程输出的%runfile并非普通 IPython 自带命令，而是 Spyder 在 IPython 内核中注册的自定义魔术命令。它的实现位于 code_runner.py，由SpyderCodeRunner类提供，并通过runfile_arguments装饰器定义了完整的参数集合（见 code_runner.py）：

内核侧的测试用例（test_console_kernel.py）专门验证了runfile在正确命名空间中执行、支持--current-namespace等行为，例如其中的test_runfile用例。这解释了为什么教程输出中会出现--wdir：Spyder 默认把运行工作目录设为脚本所在目录。

在控制台中调用函数、检查对象与更新对象

在 Console 中调用已定义的函数

执行过hello.py后，函数对象hello就存在于IPython 控制台的命名空间中。在控制台提示符（In [?]，?为执行计数）旁直接输入hello()并按Enter：

In [ ]: hello() Hello World

注意这与按F5重跑整个文件的区别：F5会让 Python 重新遍历文件、创建新的hello函数对象并执行；而在控制台调用hello()只是调用之前已在控制台命名空间中定义好的那个函数对象。

用 dir() 检查命名空间

Python 内置函数dir()会列出当前命名空间中的所有已知对象。在提示符输入dir()，暂时忽略所有以下划线（_）开头的条目，你应该能在列表中看到hello。

提示：如果你得到一长串对象列表，说明 Spyder 已经为你做了便捷导入。可以先用后文介绍的"重置命名空间"方法清空，再按F5执行hello.py，然后运行dir()验证。

用 help() 与 Ctrl-I 查看文档

一旦对象出现在当前命名空间，就可以用help函数了解它。在控制台输入help(hello)：

In [ ]: help(hello) Help on function hello in module __main__: hello() Print "Hello World" and return None.

这些信息来自两部分：参数数量与名称等信息是 Python 通过自省（inspection）获得的；而"Print "Hello World" and return None."则来自函数的docstring——即def hello():下面第一行开始的字符串，按惯例用三对双引号"""包裹。

Spyder 还提供了Help 面板（默认位于右上角）。把光标停在某个对象名上，按Ctrl-I（macOS 为Command-I），Help 面板就会自动显示与help(hello)相同的内容：

这个功能在控制台和编辑器中都有效。Help 面板的富文本渲染由前文提到的 Sphinx 管线完成，这也正是下文 docstring 格式化章节的意义所在。

更新对象：F5 全量重跑 vs F9 局部执行

假设你想修改已有函数的行为，如何让 Python 认可你的修改？

简单策略：重新执行整个程序。在编辑器中把hello改成打印Good Bye World，按F5：

Good Bye World

原理是 Python 遍历整个hello.py，创建新的hello函数对象（覆盖旧的），再执行之。

深入观察"对象持久性"，分四步验证：

1. 先把函数改回打印Hello World，按F5确认输出正确；
2. 在控制台调用hello()，看到Hello World；
3. 把函数改成打印Later World并保存文件，但不要按F5；
4. 再次在控制台调用hello()：

In [ ]: hello() Hello World

原因很明确：控制台中的hello对象仍是旧的、打印Hello World的那个。修改文件本身并不会影响控制台里已经创建的对象。要让控制台命名空间里的对象更新，有两个选择：

• 选项 1：按F5重新执行整个hello.py，创建新的hello对象并覆盖旧对象；之后调用hello()就会输出Later World；
• 选项 2：在编辑器中选择你修改过的区域（本例为整个函数，从def hello():到print("Later World")），然后选择菜单Run --> Run current line/selection或按F9。这样只把选中的代码送入控制台执行：

In [ ]: def hello(): ...: """Print "Hello World" and return None.""" ...: print("Later world") ...: In [ ]: hello() Later world

"只执行部分代码来更新对象"这一能力，在开发与调试复杂程序时价值巨大：当在控制台会话中重建某些对象/数据耗时很长时，你只需反复重跑正在修改的函数（或类、对象），其余数据可以一直复用。

Python 初学者的推荐起步步骤

进入这一节前，请确保有一个IPython 控制台处于打开状态（默认在右下角）。IPython 解释器是科学计算社区的标配；随时可以通过菜单Consoles --> Open an IPython Console新建控制台。

重置命名空间

命名空间（namespace）即控制台在当前时刻定义的所有对象的集合，可以用 IPython 的%reset命令清空。输入%reset并按Enter，确认y：

In [1]: %reset Once deleted, variables cannot be recovered. Proceed (y/[n])? y In [2]:

同样地，你可以在IPython 控制台窗格右上角的"齿轮"选项菜单中选择Remove all variables完成同样操作。执行后，会话命名空间中只剩少量对象，可用dir()列出：

In [2]: dir() Out[2]: ['In', 'Out', '__builtin__', '__builtins__', '__name__', '_dh', '_i', '_i2', '_ih', '_ii', '_iii', '_oh', '_sh', 'exit', 'get_ipython', 'quit']

如果想去掉重置时的确认步骤，可以用%reset -f，或在Remove all variables对话框中勾选Don't show again。

追求 PEP 8 代码风格

除了 Python 语法本身的约束外，社区还广泛遵循关于源码布局的《Python 源码风格指南》（PEP 8）。遵循该规范写出的代码与绝大多数 Python 程序员风格一致，更易阅读、调试与复用。Spyder 可以自动为你检查，启用方式见下一节。

精选偏好设置

偏好设置在哪里

Spyder 的大量行为都可以通过偏好设置（Preferences）配置，菜单位置因操作系统而异：

• Windows 与 Linux：菜单Tools --> Preferences
• macOS：菜单Python/Spyder --> Preferences

启用 PEP 8 违规警告

进入Tools --> Preferences --> Completion and linting --> Code style and formatting --> Code style，勾选Enable code style linting即可让 Spyder 自动按 PEP 8 检查代码风格。开启后，编辑器中会在违规行左侧出现相应的警告标记。

自动符号数学（SymPy）模式

通过Preferences --> IPython Console --> Advanced Settings --> Use symbolic math，可以激活控制台的符号数学（sympy）模式。该模式由 SymPy 提供支持，启动 IPython 控制台时会自动导入部分 SymPy 对象并报告已执行的命令，从而支持 LaTeX 风格的数学输出渲染。使用前提：系统已安装 SymPy；要看到格式化输出，还需要安装 LaTeX 发行版。

激活后控制台会报告类似这样的自动导入：

These commands were executed: >>> from sympy import * >>> x, y, z, t = symbols('x y z t') >>> k, m, n = symbols('k m n', integer=True) >>> f, g, h = symbols('f g h', cls=Function)

此后可以直接使用x、y等符号变量进行符号运算，例如：

常用功能快捷键

以下为 Spyder 的默认快捷键；标记*的项可以在偏好设置的 Keyboard shortcuts 标签页中自定义。macOS 用户请把Ctrl替换为Command，把Alt替换为Option。

关于Tab补全，教程给了很实用的例子：假设定义了mylongvariablename = 42，要写mylongvariablename + 100时，只需输入my再按Tab；若该前缀唯一，完整名称会直接补全；若不唯一，会弹出候选列表，可用Up/Down键配合Enter选择，或继续输入更多字符让候选自动收窄。

运行配置（Run configuration）

运行配置决定按F5或选择Run --> Run时，编辑器中的文件如何被控制台执行。首次运行文件时设置框会自动弹出；其他时间可以通过菜单Run --> Configure或按F6打开。配置项中有三种控制台选择。假设编辑器中有如下hello.py：

def hello(name): """Given an object 'name', print 'Hello ' and the object.""" print("Hello {}".format(name)) i = 42 if __name__ == "__main__": hello(i)

在当前控制台中执行（Execute in current console）

这是默认选项，通常也是好选择。选择该模式意味着：

代码执行后对象的持久性：程序运行完成后，你可以在运行它的控制台中与之交互，尤其可以检查、操作程序创建的对象（如i和hello函数）。这对增量编码、测试与调试很有用：你可以直接从控制台调用hello()而不必重跑整个文件（当然，修改函数后仍需重跑整个文件或至少重跑函数定义，才能让新版本在控制台可见）。

代码执行前已有对象的可见性：执行代码时，它能看到控制台会话中此前已定义的（全局）对象。这些对象可能来自之前的执行、控制台交互，或便捷导入（如from sympy import *——Spyder 可能自动执行部分便捷导入）。

这种"已有对象对代码可见"的特性容易被遗忘，而且在代码无意中依赖这些对象时会造成隐蔽错误。教程给出了经典案例：

1. 运行hello.py后，变量i成为控制台中的全局变量；
2. 你编辑源码，意外删除了i = 42这一行；
3. 再次执行该文件，hello(i)不会报错，因为控制台里恰好还有一个名为i的对象，尽管源码中已没有i的定义。

此时你保存文件后可能误以为它能在任何环境正确运行；但换一个全新的 IPython 控制台会话（或直接在系统 shell 中执行python hello.py）就会报错——i未定义。问题本质是代码使用了对象（i）却没有先创建它；模块导入也有同样的效应：如果在 IPython 提示符导入过sympy，那么在同一个控制台会话中运行的程序也能看到它。

如何确认代码不依赖这类已有对象，见下文"如何检查代码能独立正确执行"。

在专用控制台中执行（Execute in a dedicated console）

选择该模式后，每次执行hello.py都会启动一个新的 IPython 控制台。相比"在当前控制台中执行"，它最大的优势是：可以确定控制台中没有源自调试和反复执行的全局对象残留。每次运行代码，控制台都会被重启。这是一个安全的选择，但牺牲了交互式执行的灵活性。

如何检查你的代码能独立正确执行

如果你选择了"在当前控制台中执行"，有两种方法验证代码是否依赖未定义变量、未导入模块或未执行过的命令：

• 方法 1：切换到"在专用控制台中执行"模式，再从编辑器运行代码；
• 方法 2：若想留在当前控制台，先用 IPython 魔术命令%reset或Remove all variables菜单项重置命名空间，清空所有对象（如例子中的i），再从编辑器运行代码。

建议

对初学者推荐使用"在当前控制台中执行"；当一段代码完成后，用上述两种方法之一复查它能否独立运行。

其他实用观察

多文件与标签浏览

编辑器打开多个文件时，顶部的标签页按打开顺序排列，也可以随意拖动调整位置。标签左侧有"Browse tabs"图标（鼠标悬停可见），适合在打开较多文件时直接跳转。也可以按Ctrl-Tab或Ctrl-P召唤文件切换器，按最近使用顺序导航标签。

环境变量

在IPython 控制台窗口（默认布局的右下角窗口）中，点击Options菜单（"齿轮"图标），选择Show environment variables，即可显示环境变量。

重置全部自定义配置

所有保存在磁盘上的自定义配置可以通过命令行开关重置，即运行：

spyder --reset

变量浏览器中的对象操作

在Variable Explorer（变量浏览器）中右键点击对象，会显示进一步绘图与分析的操作选项。双击简单变量可以直接编辑其值；双击对象会打开新窗口显示其内容并通常允许编辑。Python 集合（列表、字典、元组等）、NumPy 数组、Pandas 的Index、Series、DataFrame、Pillow 图像等都有专门的 GUI 查看器，大部分任意 Python 对象可以像查看其dict()表示那样浏览与编辑。

文档字符串（docstring）格式化

写代码时务必编写文档字符串。Spyder 推荐使用 reStructuredText（reST）标记，并遵循科学 Python 社区通行的 Numpydoc 约定；遵循这些规范后，Help 面板会渲染出漂亮的文档。例如，要让average()函数在 Help 面板中显示成这样：

你需要这样写文档字符串：

def average(a, b): """ Return the average value (arithmetic mean) of two numbers. Parameters ---------- a : numeric A number to average. b : numeric Another number to average. Returns ------- result : numeric The average of a and b, computed using ``0.5 * (a + b)``. Example ------- >>> average(5, 10) 7.5 """ return (a + b) * 0.5

关键点在于：必须使用Parameters这个词并为其加下划线。a : numeric表示参数a的类型是numeric；紧接着的缩进行可以用来详细说明该变量代表什么、允许的类型需要满足什么条件等。所有参数以及返回值都应如此描述；通常还建议像示例一样附带一个Example。

调试（Debugging）

逐行单步执行代码

通过菜单Debug --> Debug或快捷键Ctrl-F5启动调试执行，会激活 IPython 调试器ipdb。此时编辑器会高亮即将执行的行，变量浏览器会显示程序当前执行点的上下文变量。

进入调试模式后，可以使用Debug工具栏的按钮逐行执行：

• Step按钮（或Ctrl-F10）逐行执行；
• Step Into按钮（或Ctrl-F11）进入函数内部查看其工作方式；
• Step Return按钮（或Ctrl-Shift-F12）跳出当前函数并继续执行下一行。

若想在特定位置停下来检查，需要插入断点（breakpoint）：在目标行按F12，或点击行号右侧位置，行首会出现红点表示断点；重复同样操作即可移除。

进入调试器后，按Continue按钮会直接执行到第一个断点处停下。

提示：也可以在控制台提示符下直接用命令控制调试过程：

• n：Next，移动到下一条语句；
• s：Step into，若当前语句是函数调用则进入该函数；
• r：Return，执行完当前函数中的所有语句并返回，再交还控制权。

在调试器内部，你仍可以交互式执行常规语句：给变量赋值、修改其值、定义与调用函数、设置新断点等。教程给出了一个完整示例，把下面代码放入新文件：

def demo(x): for i in range(5): print("i = {}, x = {}".format(i, x)) x = x + 1 demo(0)

直接运行（Run --> Run）会得到：

i = 0, x = 0 i = 1, x = 1 i = 2, x = 2 i = 3, x = 3 i = 4, x = 4

改用调试器运行（Debug --> Debug），不断按Step直到高亮行到达demo(0)函数调用，然后按Step Into进入函数；继续按Step逐行执行。接着在调试器提示符输入x = 10修改x，你会看到x在变量浏览器中随之变化，并被demo()函数打印出来（打印输出会穿插在调试命令与响应之间）。

这种"逐行执行、观察变量变化、手动修改变量"的调试能力，是理解代码行为（并在需要时修正它）的强大工具。要终止调试器，可以输入exit，选择菜单Debug --> Stop，或按Ctrl-Shift-F12。

异常发生后的事后调试

在IPython 控制台中，异常抛出后可以直接调用%debug：这会进入 IPython 调试模式，允许按上述方式检查异常发生处的局部变量。这比在代码里加print再重跑高效得多。

配合使用up（调试器中按u）与down（按d）命令，可以在调用栈中上下移动检查点——"上"指调用当前函数的那些函数，"下"反之。还可以随时输入pdb来启用或禁用"异常发生时自动触发调试器"的行为。

绘图：inline 还是独立窗口

你可以决定 Matplotlib 生成的图形显示在哪里：

• 内联（Inline）：直接显示在IPython 控制台中，便于通过控制台Ctrl-S保存会话记录；
• 独立窗口：带选项工具栏的新窗口，可以交互式缩放、操纵图形、设置各种绘图与显示选项，并通过菜单保存为不同文件格式。

在控制台分别使用如下命令切换：

In [ ]: %matplotlib inline

In [ ]: %matplotlib qt

其中%matplotlib qt表示由 Qt 后端渲染、图形显示在自己的窗口中。默认行为可以通过偏好设置定制：Preferences --> IPython Console --> Graphics --> Graphics Backend。

可以用下面两行快速绘图并测试以上两种模式：

In [ ]: import matplotlib.pyplot as plt In [ ]: plt.plot(range(10), 'o')

历史说明

这份教程最初源自南安普顿大学（英国）的教学讲义，作者使用它向工程师本科与博士生讲授"用于计算建模的 Python"，后由 Spyder 开发团队针对 Spyder 3.3.x 更新为现在的形态。它从"运行第一个程序"起步，一路覆盖控制台交互、命名空间管理、运行配置、代码规范、调试与绘图，是理解 Spyder 工作流的一条完整学习路径；而它的渲染入口与实现细节，都可以在 tutorial.rst、widgets.py 与内核侧的 code_runner.py 中对照查阅。

• 开发工具
• IDE
• 代码编辑器