新手必看：Playwright代码规范 | 3分钟学会

不把代码写成垃圾，是新手在用Playwright时最该知道的事。别以为写个爬虫就能上手，没规范的代码写得再快也是死路一条。我见过太多人因为没注意代码结构，导致页面加载失败、元素找不到、脚本卡死。真正能稳定运行的代码，是写了就能用、改了不翻车、调试不费劲。要想写出好代码，必须从一开始就用Playwright的代码规范。别看是小细节，它决定你后续的维护成本和出错频率。我用的配置文件里，每个任务都用单独的函数封装，这样出错能快速定位，又能复用。还有一点，别用全局变量乱传参数，用context传更安全，也更符合设计模式。

我见过最惨的案例是，有人把所有操作都写在main函数里，调试时连个trace都用不上，最后搞出一个几十万行的乱七八糟代码。这是自找麻烦。Playwright的代码规范包括上下文管理、配置分离、函数封装、断言逻辑、异常处理。你得在config文件里定义好user-agent、proxy、headless参数，别在每个脚本里写一遍。还有，别用async/await写成嵌套地狱，用Promise链或者直接await更直观。元素定位要用css选择器，别用xpath，不然你会在元素变化时反复报错。还有，别用硬编码的URL，用配置文件或环境变量替代，这样换环境时不用改代码。

我用的代码结构是，一个config文件、一个runner文件、一个test目录，test目录下每个页面单独一个文件。这样组织代码，不仅能复用，还能方便扩展。config文件里要定义好baseURL、headers、cookies、extraHTTPHeaders，别忘了在启动时加--no-sandbox和--disable-gpu参数，不然在某些系统下会卡死。runner文件里用Playwright的API初始化浏览器，用launch和connect分开，别混在一起。函数里要写好注释，说明每个步骤的作用，别以为别人会看你的代码。

代码规范不是写给别人看的，是你未来的自己回头看时，能秒懂的地方。记住，Playwright的代码风格要简洁、可读、可维护。别用复杂的结构，别写重复的代码，别忽视基础的错误处理。你可能会在爬取动态内容时遇到问题，这时候用page.waitForSelector加timeout参数能避免卡死。还有，别用page.goto直接跳转，用page.route拦截请求，能控制加载行为。在测试时，用page.pause加F12，在控制台调试是新手必备的技能。

技术参考

▌ 技术引导

代码写得乱，是新手最大的敌人。别以为用Playwright就能爬好网页，没规范的代码会让后续维护变成噩梦。我见过太多人因为没使用正确的配置方式，导致代码在不同环境里反复出错。别用硬编码写死参数，用环境变量或配置文件传参，这样更灵活。Playwright的代码规范包括上下文管理、函数封装、断言逻辑、异常处理、参数传递。这些看似简单的规则，能帮你省掉80%的调试时间。别用async/await写成嵌套地狱，用Promise链更直观。还有，元素定位别用xpath，用css选择器更稳定。

别看是你写一次，如果项目规模大一点，代码结构就显得尤为重要。我见过有人把所有操作写在一个函数里，最后代码臃肿到难以维护。正确的做法是把每个页面操作封装成独立函数，这样不仅能复用，还能方便调试。在配置文件里定义好headers、cookies、user-agent，别在每个脚本里重复写。你可能会在爬取动态内容时遇到卡顿，这时候用page.waitForSelector配合timeout参数能有效避免死循环。别用page.goto直接跳转，用page.route拦截请求能更精细地控制加载过程。

我用的代码结构是，一个config文件、一个runner文件、一个test目录。config文件里定义好baseURL、headers、cookies、extraHTTPHeaders，runner文件里初始化浏览器，用launch和connect分开。test目录下每个页面单独一个文件，这样组织代码更清晰。函数里加注释说明每个步骤的作用，别以为这是多余的。别用全局变量传递参数，用context传更安全，也更符合设计模式。你可能在测试时会遇到元素找不到的问题，这时候用page.pause加F12，在控制台调试是必须的技能。

别忽视基础的错误处理，比如用try/catch拦截异常，不然一个小小的错误就能让整个脚本崩溃。还有，别用page.click直接点击元素，用page.locator加上wait_for_selector和checkable参数能避免误操作。你在用Playwright抓取网页时，可能会遇到页面加载不全的问题，这时候用page.waitForLoadState可以确保内容准备好。别用page.evaluate直接执行JS，用page.locator和page.evaluateHandle更安全，也能减少内存泄漏风险。

技术参考

▌ 技术参考

Playwright是一个用于自动化浏览器操作的工具，它支持多种语言，包括JavaScript、Python、Java、Ruby、C#等。对于新手而言，了解其代码规范是避免后续踩坑的关键。Playwright的核心设计原则是模块化、可配置、可维护。因此，在编写代码时，必须遵循其官方推荐的结构。例如，使用page.waitForSelector方法来等待元素加载，而不是直接调用page.click。这样可以规避元素未加载完成导致的误操作。code中应使用locator方法代替直接选择元素，因为locator提供了更强的上下文控制。code中应设置合理的timeout值，避免脚本因等待时间过长而卡死。

配置文件的结构对于Playwright来说至关重要。一般情况下，应在config文件中定义baseURL、headers、cookies、extraHTTPHeaders等参数。例如，在Python中使用playwright.sync_playwright()初始化浏览器，然后通过config文件传入参数。此外，在启动浏览器时，应使用--no-sandbox和--disable-gpu参数，这样可以避免某些系统下出现的浏览器无法启动的问题。这些参数通常在config文件中通过launch方法传递。例如：browser = playwright.chromium.launch(headless=False, args=['--no-sandbox', '--disable-gpu'])。配置文件不仅提高了代码的可读性，还能在不同环境中灵活切换。

在代码编写过程中，常见的一个问题是页面加载不稳定，导致元素找不到。这时候，可以使用page.waitForLoadState('networkidle')来确保网络请求完成后再执行操作。这种方法在动态加载内容的页面上尤为有效。例如，在抓取一个需要异步加载数据的页面时，应先等待网络请求完成，再进行元素定位和操作。另一种方法是使用page.waitForSelector配合timeout参数，确保元素存在后再继续执行。如果元素始终找不到，可以尝试调整选择器或者增加等待时间。此外，在某些场景下，使用page.pause()暂停脚本，配合F12调试工具可以帮助新手快速定位问题。

在处理动态网页时，需要注意页面加载的时机。比如，某些页面加载完成后还会继续发起请求，这时候使用page.waitForLoadState('networkidle')会更可靠。但如果你只是需要等待页面渲染完成，page.waitForSelector会更高效。在使用playwright的时候，应该根据实际需求选择合适的等待策略。如果页面内容是通过JavaScript动态生成的，使用page.waitForFunction能够更精准地等待特定条件满足。例如，在等待某个元素出现时，可以设置page.waitForFunction('() => document.querySelector("your-selector") !== null')。这种写法能提高脚本的健壮性和稳定性。

在使用Playwright进行API测试时，可以通过page.route方法拦截请求，直接操作响应内容。例如，在拦截某个特定请求时，可以设置page.route('https://example.com/api/', async (route) => { await route.fulfill({ response: Response.fromURL('https://example.com/fake-response.json') }) } )。这种方法能有效控制请求和响应，适用于需要模拟网络行为的测试场景。同时，在处理JSON响应时，应使用page.evaluateHandle方法来获取数据，而不是直接使用page.evaluate，这样能避免内存泄漏问题。此外，使用headers参数传递认证信息，能提高请求的准确性和安全性。

在运行Playwright脚本时，需要注意浏览器启动的配置。例如，在使用playwright.sync_playwright()时，可以通过args参数传递--no-sandbox和--disable-gpu，以避免某些系统环境下的兼容性问题。同时，在启动浏览器时，应确保使用正确的headless模式。如果在非headless模式下运行，可以使用page.pause()暂停脚本，便于调试。此外，在使用playwright.launch()方法时，应考虑是否开启--slowmo参数，这样可以在执行脚本时更直观地看到每一步操作，便于新手调试。这些配置项在实际使用中非常关键，能帮助避免很多不必要的麻烦。

在处理cookie和headers时，需要注意它们的正确使用方式。例如，在初始化浏览器时，可以使用context.addCookies方法添加cookie，或者在请求时通过headers参数传递认证信息。如果页面需要登录，可以通过page.route拦截登录请求，伪造响应或添加headers来绕过验证。此外，在某些场景下，使用context.setUserAgent方法修改用户代理，能帮助爬虫绕过反爬机制。需要注意的是，修改headers时应使用Object.assign方法来合并原有参数，避免覆盖掉关键信息。这些操作在实际项目中有大量应用，是新手必须掌握的基础技能。

在处理元素定位时，应该使用更稳定的方法。例如，使用page.locator方法代替直接选择元素，因为locator提供了更强大的上下文控制。在定位元素时，可以使用page.locator('your-selector')配合wait_for_selector和checkable参数，确保元素存在并可操作。如果元素存在但不可点击，可以使用page.locator('your-selector').click()方法，这样能避免因元素未准备好导致的误操作。此外，在处理页面跳转时，应使用page.waitForNavigation方法等待页面加载完成，而不是直接调用page.click。这些方法在实际使用中能有效减少出错率。

在使用Playwright进行单元测试时，应该遵循模块化和可复用的原则。例如，将每个页面的操作封装成独立函数，这样能提高代码的可读性和可维护性。函数中应使用page.waitForSelector和page.locator方法进行元素定位，避免直接使用document.querySelector导致的稳定性问题。此外，在编写测试用例时，应使用assertions来验证结果是否符合预期。例如，使用page.locator('your-selector').textContent()获取内容，并用expect.assertions进行断言。这种方法能帮助新手更好地理解测试逻辑，也能提高代码的健壮性。

在处理异常和错误时，应该使用try/catch块进行捕获。例如，在执行某些可能出错的操作时，如page.click或page.fill，可以使用try/catch来拦截错误并进行处理。此外，在使用page.pause()暂停脚本时，应确保在调试完成后及时移除，否则会导致脚本无法自动运行。同时，在处理动态生成的元素时，应使用page.waitForSelector配合timeout参数，避免脚本因等待时间过长而卡死。这些错误处理机制在实际项目中能有效减少崩溃率，提高代码的稳定性。

在使用Playwright进行API测试时，应考虑使用不同的测试方式。例如，在使用page.route拦截请求时，可以使用Response.fromURL方法伪造响应，这样能模拟不同的返回结果。此外，在测试HTTPS请求时，应使用page.route('https://example.com/', async (route) => { ... })来拦截请求，并返回预设的响应内容。这种方法能帮助新手更好地理解网络请求的处理逻辑，也能提高测试的可控性和准确性。在实际应用中，这些方法能有效减少测试中的不确定性。

在使用Playwright进行页面截图时，应注意一些关键参数。例如，使用page.screenshot({'path': 'screenshot.png', 'fullPage': true})可以获取整个页面的截图，而不仅仅是当前视口的内容。此外，在截图时应考虑添加wait_for_selector参数，确保页面元素已经加载完成后再截图。例如，page.waitForSelector('your-selector', { timeout: 5000 }).screenshot(...)。这种写法能避免截图失败或内容不完整的问题。在进行自动化测试时，这些截图功能能帮助快速定位问题。

在使用Playwright处理文件上传时，应使用page.setInputFiles方法，而不是直接使用input元素。例如，在定位到文件上传框后，可以使用page.setInputFiles('your-input', ['file1.txt', 'file2.txt'])来上传文件。这种方法比直接操作input元素更可靠，也能避免因为页面未加载完成导致的上传失败问题。此外，在处理文件上传时，应确保文件路径正确，否则会导致脚本崩溃。在实际项目中，这些处理方式能有效避免文件上传相关的错误。

在处理表单提交时，应该使用page.locator('your-form').submit()方法，而不是直接使用page.click('submit-button')。这种方法能确保表单提交的稳定性，也能避免因为某些元素未加载完成导致的提交失败。此外，在提交表单前，应使用page.waitForLoadState('networkidle')确保所有相关请求已经完成。如果提交后需要处理响应，可以通过page.waitForNavigation来等待页面跳转。这些操作在实际应用中非常常见，是新手必须掌握的基础技巧。

在处理动态元素时，应使用page.waitForSelector配合timeout参数，避免脚本因等待时间过长而卡死。例如，在等待某个元素出现时，可以设置page.waitForSelector('your-selector', { timeout: 5000 })。如果元素始终找不到，可以尝试调整选择器或者增加等待时间。此外，在使用page.locator方法时，可以添加wait_for_selector和checkable参数，确保元素存在且可操作。这些方法能有效提高脚本的稳定性，避免因页面渲染问题导致的失败。

在处理页面跳转时，应使用page.waitForNavigation方法确保页面加载完成。例如，在执行page.click('your-button')后，可以使用page.waitForNavigation({'waitUntil': 'networkidle'})来等待跳转完成。这种方法比直接等待时间更可靠，也能提高脚本的执行效率。在某些情况下，page.waitForNavigation可以结合page.waitForLoadState使用，以确保页面不仅跳转完成，而且内容也已经准备好。这些操作在自动化测试中非常关键，是新手必须掌握的技能。