1. 项目概述与核心价值

最近在社区里看到不少朋友想用Python写个小游戏练手，五子棋是个经典的选择。它规则简单，但实现起来却能覆盖游戏开发的几个核心环节：图形界面、用户交互、游戏逻辑和算法判断。直接用Python的Pygame库来搞，上手快，成就感也足。我自己几年前第一次用Pygame写五子棋时，踩了不少坑，尤其是棋子画出来有锯齿、棋盘线对不齐，还有那个胜负判断逻辑写出来又慢又容易出错。所以这次，我打算从一个过来人的角度，带你走一遍完整的流程，但重点会放在两个最容易出问题的地方：如何让棋子画得圆润清晰，以及如何写出既高效又准确的胜负判断逻辑。这不仅仅是完成一个作业，更是理解一个可维护、体验好的小项目应该怎么构建。无论你是刚学完Python基础语法想找点实战，还是对游戏逻辑实现感兴趣，这篇内容都能给你直接的代码参考和背后的思考。

2. 环境搭建与项目初始化

2.1 Pygame安装与基础窗口创建

首先，确保你的Python环境已经就绪。我推荐使用Python 3.7及以上版本，兼容性和库支持都比较好。安装Pygame非常简单，打开你的终端或命令提示符，用pip一键安装：

pip install pygame

安装完成后，我们就可以开始搭建游戏的骨架了。创建一个新的Python文件，比如叫做gobang.py。第一步永远是初始化Pygame并创建游戏窗口。

import pygame import sys # 初始化pygame pygame.init() # 定义颜色，方便后续使用 BACKGROUND = (220, 179, 92) # 棋盘背景色，仿木色 LINE_COLOR = (0, 0, 0) # 棋盘线颜色，黑色 BLACK = (0, 0, 0) # 黑棋颜色 WHITE = (255, 255, 255) # 白棋颜色 RED = (255, 0, 0) # 高亮或提示色 # 定义棋盘和窗口参数 GRID_SIZE = 15 # 15x15的标准五子棋盘 GRID_WIDTH = 40 # 每个格子的像素宽度 MARGIN = 50 # 棋盘边距 PIECE_RADIUS = 18 # 棋子半径 # 计算窗口大小 WINDOW_WIDTH = 2 * MARGIN + GRID_WIDTH * (GRID_SIZE - 1) WINDOW_HEIGHT = WINDOW_WIDTH # 通常棋盘是正方形的 # 创建游戏窗口 screen = pygame.display.set_mode((WINDOW_WIDTH, WINDOW_HEIGHT)) pygame.display.set_caption('五子棋 - Python+Pygame 实现') # 游戏主循环的退出标志 running = True while running: for event in pygame.event.get(): if event.type == pygame.QUIT: running = False # 填充背景色 screen.fill(BACKGROUND) # 更新屏幕显示 pygame.display.flip() # 退出pygame pygame.quit() sys.exit()

这段代码运行后，你会看到一个涂成木黄色的窗口。GRID_WIDTH和MARGIN这两个参数很重要，它们决定了棋盘的大小和位置。MARGIN留出边缘，让棋盘看起来更美观，也方便后续可能添加的状态栏。GRID_WIDTH乘以(GRID_SIZE - 1)是因为15个格子之间有14条间隔。

注意：在游戏开发中，坐标计算是基础也是容易出错的地方。务必想清楚像素坐标和逻辑网格坐标的转换关系。这里我们采用一个常见的模型：棋盘线的交点就是棋子的落点，这些交点的逻辑坐标是 (0,0) 到 (14,14)，对应的屏幕像素坐标则需要通过MARGIN + col * GRID_WIDTH和MARGIN + row * GRID_WIDTH来计算。

2.2 数据结构设计：棋盘与游戏状态

在画棋盘和棋子之前，我们需要一个数据结构来记录棋盘的状态。一个二维列表是最直观的选择。

# 初始化一个15x15的棋盘，0表示空位，1表示黑棋，2表示白棋 board = [[0 for _ in range(GRID_SIZE)] for _ in range(GRID_SIZE)] # 记录当前轮到哪一方下棋，1为黑棋，2为白棋 current_player = 1 # 记录游戏是否结束 game_over = False # 记录最后一步落子的位置，用于高亮显示或AI计算，初始为None last_move = None

为什么用0、1、2而不用字符串或更复杂的对象？对于这种状态固定的简单游戏，使用整数效率最高，内存占用小，后续在判断胜负进行大量比较时速度也快。last_move这个变量不是必须的，但它非常有用，比如我们可以在棋盘上高亮显示最后落下的那颗棋子，提升用户体验；未来如果想加入AI，AI也常常需要关注最后一步来评估局势。

3. 核心模块一：棋盘与棋子的绘制优化

3.1 绘制清晰的棋盘网格

绘制棋盘就是画一组横线和一组竖线。关键是要画得直，交点要对齐。

def draw_board(surface): """在给定的surface上绘制棋盘网格""" # 绘制横线 for row in range(GRID_SIZE): start_pos = (MARGIN, MARGIN + row * GRID_WIDTH) end_pos = (WINDOW_WIDTH - MARGIN, MARGIN + row * GRID_WIDTH) pygame.draw.line(surface, LINE_COLOR, start_pos, end_pos, 2) # 线宽为2 # 绘制竖线 for col in range(GRID_SIZE): start_pos = (MARGIN + col * GRID_WIDTH, MARGIN) end_pos = (MARGIN + col * GRID_WIDTH, WINDOW_HEIGHT - MARGIN) pygame.draw.line(surface, LINE_COLOR, start_pos, end_pos, 2) # 绘制棋盘上的五个小黑点（天元和星），这是标准五子棋盘的标志 dots = [(3, 3), (3, 11), (7, 7), (11, 3), (11, 11)] for dot in dots: col, row = dot center_x = MARGIN + col * GRID_WIDTH center_y = MARGIN + row * GRID_WIDTH pygame.draw.circle(surface, LINE_COLOR, (center_x, center_y), 5)

这里有个细节，线宽我设置为2。1可能太细，在有些屏幕上不明显；太粗又会显得笨重。2是个比较折中的选择。画点的时候，(7,7)是天元，其他四个是星位，它们的坐标是固定的。

3.2 优化棋子绘制：抗锯齿与视觉增强

这是第一个重点优化部分。直接用pygame.draw.circle画出来的圆，边缘会有明显的锯齿（像素阶梯感），看起来很粗糙。Pygame提供了pygame.gfxdraw模块中的aacircle和filled_circle函数来绘制抗锯齿的圆，但需要注意，pygame.gfxdraw模块可能需要单独导入，且其函数参数顺序与draw模块略有不同。

更现代、更推荐的方法是使用pygame.draw.circle的width参数结合多层绘制来模拟平滑效果。下面是我经过多次尝试后总结出的一个效果很好的绘制函数：

def draw_piece(surface, col, row, player, is_last=False): """ 在指定位置绘制一颗棋子 Args: surface: 绘制表面 col, row: 棋子在棋盘上的逻辑坐标 (0-14) player: 1为黑棋，2为白棋 is_last: 是否为最后落下的棋子，用于高亮 """ # 计算屏幕像素坐标 center_x = MARGIN + col * GRID_WIDTH center_y = MARGIN + row * GRID_WIDTH color = BLACK if player == 1 else WHITE highlight_color = RED # 高亮颜色 # 方法一：使用pygame.gfxdraw实现抗锯齿（需导入） # import pygame.gfxdraw # pygame.gfxdraw.filled_circle(surface, center_x, center_y, PIECE_RADIUS, color) # pygame.gfxdraw.aacircle(surface, center_x, center_y, PIECE_RADIUS, color) # 方法二：更兼容、效果可控的多层绘制法（推荐） # 1. 绘制一个稍大的、颜色稍浅的圆作为“光晕”或“底衬”，增加立体感和平滑度 if player == 1: # 黑棋 # 给黑棋加一个灰色的外圈，使其在木色背景上更突出 pygame.draw.circle(surface, (50, 50, 50), (center_x, center_y), PIECE_RADIUS + 1) else: # 白棋 # 给白棋加一个很浅的灰色外圈，避免和背景融为一体 pygame.draw.circle(surface, (240, 240, 240), (center_x, center_y), PIECE_RADIUS + 1) # 2. 绘制主棋子的实心圆 pygame.draw.circle(surface, color, (center_x, center_y), PIECE_RADIUS) # 3. 为白棋增加一个更小的、颜色稍深的内部圆，模拟反光，增强立体感 if player == 2: inner_radius = PIECE_RADIUS - 4 pygame.draw.circle(surface, (230, 230, 230), (center_x, center_y), inner_radius) # 4. 如果是最后落下的棋子，在棋子中心画一个小的红色圆点作为高亮 if is_last: pygame.draw.circle(surface, highlight_color, (center_x, center_y), 5)

为什么这么做？

• 抗锯齿：单纯画一个实心圆，边缘像素是“非黑即白”的，锯齿感强。通过先画一个稍大、颜色过渡的圈，再画主圆，边缘的像素颜色有一个渐变，视觉上就平滑了很多。这比直接使用gfxdraw兼容性更好（某些Pygame安装可能不包含此模块）。
• 立体感：尤其是白棋，在浅色背景上可能不显眼。通过添加一个浅灰色外圈和一个更亮的内部高光，棋子立刻就有了“凸起”的质感，更像真实的玻璃棋子。
• 高亮提示：标记最后一步对于玩家跟踪对局进程非常有帮助，是一个提升用户体验的细节。

3.3 整合绘制与主循环更新

现在，我们将绘制函数整合到主循环中，并加入根据board数据绘制所有棋子的逻辑。

def draw_all_pieces(surface): """绘制棋盘上所有的棋子""" for row in range(GRID_SIZE): for col in range(GRID_SIZE): player = board[row][col] if player != 0: # 如果有棋子 # 判断是否是最后一步 is_last = (last_move is not None and row == last_move[0] and col == last_move[1]) draw_piece(surface, col, row, player, is_last) # 在游戏主循环的绘制部分更新 while running: for event in pygame.event.get(): if event.type == pygame.QUIT: running = False screen.fill(BACKGROUND) # 清屏 draw_board(screen) # 画棋盘 draw_all_pieces(screen) # 画所有棋子 pygame.display.flip() # 更新整个屏幕

现在运行程序，你应该能看到一个清晰的棋盘。虽然还没有交互，但我们已经有了一个视觉效果不错的静态棋盘。绘制优化的工作基本完成，接下来是游戏逻辑的核心。

4. 核心模块二：鼠标交互与落子逻辑

4.1 将像素坐标转换为棋盘坐标

玩家点击屏幕，我们需要将鼠标的(x, y)像素坐标，转换成棋盘的(row, col)逻辑坐标。这里涉及一个“吸附”逻辑：因为玩家很难精准点击到交叉点上，我们需要设置一个有效点击半径。

def get_board_pos(mouse_x, mouse_y): """ 将鼠标坐标转换为最近的棋盘交叉点坐标。 如果点击位置离任何一个交叉点太远，则返回None。 """ # 定义一个有效吸附半径，通常略小于棋子半径 snap_radius = PIECE_RADIUS // 2 + 5 for row in range(GRID_SIZE): for col in range(GRID_SIZE): # 计算当前交叉点的屏幕坐标 center_x = MARGIN + col * GRID_WIDTH center_y = MARGIN + row * GRID_WIDTH # 计算鼠标到该交叉点的距离 distance = ((mouse_x - center_x) ** 2 + (mouse_y - center_y) ** 2) ** 0.5 # 如果距离在吸附半径内，且该位置为空，则返回此坐标 if distance < snap_radius and board[row][col] == 0: return row, col return None

这个函数遍历所有交叉点，计算距离。snap_radius的设置是关键：太小了玩家很难点中，体验差；太大了又可能误点到非目标位置。通常设置为棋子半径的一半到三分之二比较合适。同时，我们检查目标位置是否为空（board[row][col] == 0），实现了禁止重复落子的基本规则。

4.2 处理鼠标点击事件

在主循环的事件处理部分，我们需要响应鼠标点击事件。

while running: for event in pygame.event.get(): if event.type == pygame.QUIT: running = False elif event.type == pygame.MOUSEBUTTONDOWN and not game_over: # 只在游戏未结束时响应鼠标点击 if event.button == 1: # 左键点击 mouse_x, mouse_y = event.pos pos = get_board_pos(mouse_x, mouse_y) if pos is not None: row, col = pos # 在棋盘上放置当前玩家的棋子 board[row][col] = current_player # 记录最后一步 last_move = (row, col) # 检查是否获胜 if check_win(row, col, current_player): game_over = True winner = current_player else: # 切换玩家 current_player = 3 - current_player # 巧妙切换1和2

这里用了一个小技巧current_player = 3 - current_player。因为当前玩家不是1（黑）就是2（白），用3减去当前值，1变2，2变1，就实现了轮流下棋。这比用if语句判断更简洁。

5. 核心模块三：高效且准确的胜负判断逻辑

这是整个项目的第二个重点，也是算法核心。一个低效的判断函数会让游戏在后期变得卡顿，而一个有漏洞的判断则会让游戏体验崩溃。

5.1 朴素算法的问题分析

最直观的想法是：每当落下一子，就以该子为中心，向四个方向（横、竖、左斜、右斜）搜索，看看是否有连续五个同色棋子。这个思路没错，但实现上容易写出低效或错误的代码。常见的问题有：

1. 重复计算：向一个方向搜索完，又向相反方向搜索，其实是在检查同一条线。
2. 边界处理错误：搜索时数组索引可能越界。
3. 逻辑冗余：用了多层循环和复杂条件，难以理解和维护。

5.2 优化后的方向向量检查法

我推荐使用“方向向量”法。定义四个方向，每个方向用一个(dx, dy)元组表示。然后，对每个方向，向两个相反方向延伸计数。

def check_win(row, col, player): """ 检查在(row, col)位置落子后，玩家player是否获胜。 返回True如果获胜，否则返回False。 """ # 四个检查方向：水平、垂直、左上-右下对角线、左下-右上对角线 directions = [(0, 1), (1, 0), (1, 1), (1, -1)] for dx, dy in directions: count = 1 # 计数包括当前新落的这颗子 # 向正方向延伸计数 step = 1 while True: new_row = row + dx * step new_col = col + dy * step # 检查是否在棋盘内且棋子颜色相同 if 0 <= new_row < GRID_SIZE and 0 <= new_col < GRID_SIZE and board[new_row][new_col] == player: count += 1 step += 1 else: break # 向反方向延伸计数 step = 1 while True: new_row = row - dx * step new_col = col - dy * step if 0 <= new_row < GRID_SIZE and 0 <= new_col < GRID_SIZE and board[new_row][new_col] == player: count += 1 step += 1 else: break # 如果某个方向连续棋子数达到5，则获胜 if count >= 5: return True return False

为什么这个算法更优？

1. 清晰：四个方向循环，逻辑一致，代码简洁。
2. 高效：对于每一步落子，最多检查4 * (8+8) = 64个位置（实际上远少于这个数，因为遇到空位或异色棋子就会停止），是常数时间复杂度 O(1)，与棋盘大小无关。
3. 准确：count >= 5的判断涵盖了“长连”的情况（即超过五子连珠）。标准五子棋规则中，黑棋有“禁手”规则限制长连，但作为基础实现，我们先简单处理为超过五子也算赢。如果你要实现标准规则，可以在这里修改。
4. 易于调试：每个方向独立检查，如果出现问题，很容易定位是哪个方向的计算有误。

5.3 边界情况与测试

在实现后，一定要测试边界情况：

• 棋盘边缘落子：算法中的索引检查0 <= new_row < GRID_SIZE确保了不会访问棋盘外的位置。
• 四连珠但被阻断：当延伸遇到空位或对方棋子时，while循环会break，计数停止，确保了准确性。
• 多组连珠：算法检查所有四个方向，只要有一个方向满足条件即返回胜利。

你可以通过手动修改board的初始状态，或者写一个简单的测试函数来验证算法的正确性。

# 一个简单的测试用例 def test_check_win(): global board # 清空棋盘 board = [[0 for _ in range(GRID_SIZE)] for _ in range(GRID_SIZE)] # 模拟一个水平五连珠 test_row = 7 for i in range(5): board[test_row][i] = 1 # 在最后一个子位置检查 assert check_win(test_row, 4, 1) == True print("水平五连测试通过！") # 可以继续添加垂直、斜向的测试...

6. 游戏状态完善与用户体验增强

6.1 显示当前玩家与获胜信息

游戏需要给玩家明确的反馈。我们可以在棋盘上方或下方绘制一个状态栏。

def draw_game_info(surface, current_player, game_over, winner): """在屏幕顶部绘制游戏状态信息""" font = pygame.font.SysFont(None, 36) # 使用系统默认字体，大小36 info_area_rect = pygame.Rect(0, 0, WINDOW_WIDTH, MARGIN - 10) if game_over: text = f"游戏结束！{'黑棋' if winner == 1 else '白棋'}获胜！" color = RED else: text = f"当前回合：{'黑棋' if current_player == 1 else '白棋'}" color = BLACK if current_player == 1 else (100, 100, 100) # 白棋回合时用灰色 text_surface = font.render(text, True, color) # 将文字居中显示在信息区域 text_rect = text_surface.get_rect(center=info_area_rect.center) surface.blit(text_surface, text_rect)

在主循环的绘制部分调用这个函数：draw_game_info(screen, current_player, game_over, winner)。注意，你需要提前定义winner变量。

6.2 增加重新开始功能

一局结束后，玩家肯定想再来一局。我们可以通过监听键盘事件（比如按R键）来重置游戏。

def reset_game(): """重置游戏所有状态""" global board, current_player, game_over, last_move, winner board = [[0 for _ in range(GRID_SIZE)] for _ in range(GRID_SIZE)] current_player = 1 game_over = False last_move = None winner = None # 在主循环的事件处理部分添加 while running: for event in pygame.event.get(): # ... 之前的QUIT和MOUSEBUTTONDOWN事件 ... elif event.type == pygame.KEYDOWN: if event.key == pygame.K_r: # 按下R键 reset_game()

这样，游戏结束后，按一下R键，棋盘清空，状态重置，就可以开始新的一局了。

6.3 落子音效（可选增强）

音效能极大提升游戏体验。Pygame播放音效很简单。

# 在初始化部分加载音效（确保项目目录下有click.wav文件） try: drop_sound = pygame.mixer.Sound("click.wav") drop_sound.set_volume(0.3) # 设置音量 except: print("未找到音效文件，将继续无声运行。") drop_sound = None # 在成功落子后播放音效 if pos is not None: row, col = pos board[row][col] = current_player last_move = (row, col) if drop_sound: drop_sound.play() # 播放落子音效 # ... 后续的检查胜负和切换玩家逻辑 ...

音效文件（如click.wav）需要放在与你的Python脚本相同的目录下。添加一个try-except块是为了让程序在缺少音效文件时也能正常运行，增强鲁棒性。

7. 性能优化与代码重构建议

7.1 局部刷新与脏矩形更新

目前，我们每一帧都用screen.fill()清空整个屏幕，然后重画所有元素（棋盘线、所有棋子、文字）。对于15x15的棋盘来说，这完全不是问题。但如果棋盘更大，或者画面元素更复杂，频繁的全屏重绘可能会成为性能瓶颈。

Pygame支持“脏矩形更新”。其思想是只更新屏幕上发生变化的部分区域，而不是整个屏幕。

# 在主循环中，将 pygame.display.flip() 替换为以下逻辑 changed_rects = [] # 1. 在每次绘制棋子或文字时，记录其被覆盖的区域（矩形） # 例如，在draw_piece函数末尾，可以返回棋子的外接矩形 piece_rect = pygame.Rect(center_x - PIECE_RADIUS, center_y - PIECE_RADIUS, PIECE_RADIUS * 2, PIECE_RADIUS * 2) changed_rects.append(piece_rect) # 2. 在绘制文字时也记录其矩形区域 changed_rects.append(text_rect) # 3. 在主循环末尾，只更新这些发生变化的区域 pygame.display.update(changed_rects)

对于我们的五子棋，棋盘背景是纯色，棋子落下后不会移动，所以每次落子后，我们只需要更新三个区域：新棋子覆盖的区域、之前高亮棋子恢复的区域（如果有的话）、状态文字变化的区域。实现起来稍复杂，但能显著提升在大画面或低性能设备上的运行效率。作为入门项目，全屏刷新完全够用，但了解这个优化思路对以后做更复杂的游戏很有帮助。

7.2 模块化与代码组织

随着功能增加，把所有代码都放在主循环里会变得难以阅读和维护。好的做法是将代码拆分成函数和类。

# 建议的项目结构（在不同.py文件中）： # main.py - 主程序入口，包含游戏主循环 # game.py - 定义Game类，包含board, current_player等状态和核心方法（如check_win, place_piece） # renderer.py - 定义Renderer类，负责所有绘制工作（draw_board, draw_piece, draw_info） # constants.py - 定义所有常量（颜色、尺寸、方向向量等） # 在main.py中 from game import Game from renderer import Renderer def main(): pygame.init() game = Game() renderer = Renderer() # ... 主循环，调用 game.handle_event(event), game.update(), renderer.draw(game) ...

这样拆分后，逻辑清晰，易于测试和扩展。例如，如果你想换一套棋子皮肤，只需修改Renderer类中的draw_piece方法；如果想修改规则（如禁手），只需修改Game类中的相关方法。

8. 常见问题与调试技巧实录

8.1 棋子绘制位置偏移或不对齐

问题现象：棋子没有准确落在棋盘线的交叉点上，或者棋盘线本身画歪了。排查步骤：

1. 检查坐标计算：确认MARGIN、GRID_WIDTH、GRID_SIZE的值。计算交叉点屏幕坐标的公式center_x = MARGIN + col * GRID_WIDTH是关键。可以在绘制棋盘时，在每个交叉点画一个很小的红点来辅助调试。
2. 检查绘制顺序：必须先画棋盘线，再画棋子。否则棋子会被线盖住一部分。
3. 检查吸附逻辑：get_board_pos函数中的snap_radius是否合理？可以临时将其画成一个圆圈可视化，看看有效点击范围有多大。同时检查距离计算是否正确（使用了欧几里得距离）。

8.2 胜负判断失灵（误判或漏判）

问题现象：五子连珠了没判赢，或者没到五子就判赢了。排查步骤：

1. 打印调试信息：在check_win函数内部，打印出每个方向的count值。落子后，手动在控制台查看计数是否正确。
2. 可视化检查：写一个临时函数，把当前board状态以文本形式打印到控制台（用1、2、0表示），直观地看棋盘局面。
3. 重点检查方向向量：确认directions列表中的四个元组是否正确代表了横、竖、两条斜线。(1, -1)这个方向很容易写错成(-1, 1)，它们代表的是不同的对角线。
4. 检查边界条件：在while循环中，new_row和new_col的索引检查0 <= new_row < GRID_SIZE是否写对了？必须是小于GRID_SIZE，因为索引从0开始。

8.3 游戏运行卡顿或闪烁

问题现象：画面更新不流畅，有闪烁感。原因与解决：

1. 帧率过高：主循环没有限制帧率，会以最高速度运行，占用大量CPU。在循环末尾添加pygame.time.Clock().tick(60)可以将帧率限制在60FPS，足够流畅且节省资源。
2. 绘制效率：确保没有在每一帧进行不必要的、耗时的计算（比如频繁创建字体对象）。字体对象pygame.font.Font应该在初始化时创建一次并复用。
3. 全屏刷新：如前所述，如果确实需要优化，可以考虑脏矩形更新。

8.4 音效无法播放

问题现象：程序运行没有报错，但听不到落子声音。排查步骤：

1. 检查文件路径和格式：确保click.wav文件确实存在于程序运行的当前目录下。WAV格式兼容性最好。
2. 检查音量：set_volume(0.3)可能设得太低，可以暂时设为1.0测试。
3. 初始化混音器：有时需要显式初始化音频。在pygame.init()后，可以尝试pygame.mixer.init()。
4. 静音检查：检查系统或应用是否被静音。

8.5 代码重构时的典型错误

当你开始把代码拆分成函数和类时，容易遇到变量作用域的问题。问题：在函数内部修改了全局变量（如board,current_player），但忘记使用global关键字声明，导致修改无效。解决：对于在函数内需要修改的全局变量，必须在函数内部第一行用global variable_name声明。更好的做法是彻底避免使用全局变量，而是使用类将状态封装起来，通过对象的方法来修改其属性。这是我强烈推荐的做法，它能让代码更健壮，更易管理。从基于全局变量的脚本式代码，过渡到面向对象的封装，是Python编程能力提升的重要一步。