woocommerce/.ai/skills/woocommerce-dev-cycle/zh-cn/code-quality.md

代码质量命令

目录

• 概述
• PHP 代码检查
• JavaScript 代码检查
• Markdown 代码检查
• 重要的代码检查指南
• 示例工作流程
• 理解代码检查输出
• 提交前检查清单
• 与开发周期集成
• 其他代码检查工具
• 故障排除
• 备注

概述

在对 WooCommerce 代码库进行更改时，请运行这些命令以确保代码质量并遵循编码标准。

有关详细的 PHP 代码检查样板和常见问题，请参阅 php-linting-patterns.md。

有关 Markdown 代码检查规则和工作流程，请参阅 markdown-linting.md。

PHP 代码检查

检查 PHP 代码问题

pnpm run lint:changes:branch:php

检查已更改文件是否存在违反 WordPress 编码标准的问题（只读）。

修复 PHP 代码风格问题

# 自动修复 PHP 代码风格问题
pnpm run lint:php:fix

此命令：

• 自动修复可修复的代码风格违规问题
• 应用 WordPress 编码标准格式
• 直接修改文件
• 应在提交前运行

高级 PHP 代码检查

如果您需要更多控制，可以直接使用 phpcs 和 phpcbf：

# 检查特定文件或目录
vendor/bin/phpcs path/to/file.php

# 使用特定标准检查
vendor/bin/phpcs --standard=WordPress path/to/file.php

# 修复特定文件
vendor/bin/phpcbf path/to/file.php

# 显示所有违规（包括警告）
vendor/bin/phpcs -s path/to/file.php

JavaScript 代码检查

检查 JS 代码问题

# 对分支中的更改运行 JS 代码检查
pnpm run lint:changes:branch:js

此命令：

• 仅检查当前分支中更改的 JavaScript/TypeScript 文件
• 识别代码风格和潜在问题
• 不修改文件

重要： 插件级别的 .eslintignore 排除了 client/blocks/，因此 lint:changes:branch:js 不会捕获区块代码中的 eslint 或 prettier 问题。对于区块更改，还需运行区块包的代码检查：

# 检查区块 JS/TS（通过 eslint 插件包含 prettier）
pnpm --filter=@woocommerce/block-library lint:js

# 自动修复区块 JS/TS 问题
pnpm --filter=@woocommerce/block-library lint:js-fix

有关详细的 JavaScript/TypeScript 代码检查配置和样板，请参阅 client/admin/CLAUDE.md。

Markdown 代码检查

在更改后总是检查 Markdown 文件。完整详情请参阅 markdown-linting.md。

快速命令：

# 自动修复大多数问题
markdownlint --fix path/to/file.md

# 检查剩余错误
markdownlint path/to/file.md

重要代码检查指南

仅修复您分支中的代码

重要： 仅修复您正在工作的分支中新增或修改的代码的代码检查错误。

除非特别要求，否则不要修复无关代码中的代码检查错误。

为什么？

• 保持拉取请求专注于实际更改
• 避免与其他分支发生合并冲突
• 使代码审查更容易
• 保持清晰的 Git 历史

示例工作流程

# 1. 进行您的代码更改
# ... 编辑文件 ...

# 2. 检查您所做的更改
git status
git diff

# 3. 对您的更改运行代码检查
pnpm run lint:changes:branch:php

# 4. 自动修复问题
pnpm run lint:php:fix

# 5. 查看修复内容
git diff

# 6. 如果需要，检查 JavaScript 更改
pnpm run lint:changes:branch:js

# 7. 提交您的更改
git add .
git commit -m "您的提交消息"

理解代码检查输出

PHP CodeSniffer 输出

文件: /path/to/file.php
----------------------------------------------------------------------
发现 2 个错误影响 2 行
----------------------------------------------------------------------
 12 | 错误 | [x] 期望在左括号后有 1 个空格；
    |       |     但找到 0 个
 25 | 错误 | [ ] 变量 "$orderID" 不是有效的蛇形命名法
    |       |     格式
----------------------------------------------------------------------

图例说明:

• [x] - 可通过 phpcbf/lint:php:fix 自动修复
• [ ] - 需要手动修复

常见 PHP 问题

1. 间距问题 - 通常可自动修复

   // 错误
   if($condition){
   
   // 正确
   if ( $condition ) {
   

2. 命名约定 - 需要手动修复

   // 错误
   $orderID
   
   // 正确
   $order_id
   

3. Yoda 条件 - 需要手动修复

   // 错误
   if ( $value === 'active' )
   
   // 正确
   if ( 'active' === $value )
   

提交前检查清单

在提交更改前：

• 运行 pnpm run lint:changes:branch:php
• 如果发现问题，运行 pnpm run lint:php:fix
• 如果修改了 JS 文件，运行 pnpm run lint:changes:branch:js
• 如果修改了区块 JS/TS 文件，运行 pnpm --filter=@woocommerce/block-library lint:js-fix
• 使用 git diff 查看所有自动修复
• 处理任何无法自动修复的剩余问题
• 运行测试以确保修复没有破坏功能

与开发周期集成

代码质量检查适应整体开发工作流程：

1. 进行代码更改
2. 运行相关测试（参见 running-tests.md）
3. 运行代码检查 ← 您在这里
4. 修复代码质量问题 ← 您在这里
5. 仅在测试通过且代码检查无误后提交更改

其他代码检查工具

运行其他 pnpm 脚本

WooCommerce 可能包含额外的代码检查脚本。检查可用脚本：

# 查看所有可用脚本
pnpm run

# 常见的额外脚本可能包括：
pnpm run lint           # 检查所有文件
pnpm run lint:fix       # 修复所有可自动修复的问题
pnpm run lint:php       # 仅进行 PHP 检查
pnpm run lint:js        # 仅进行 JavaScript 检查

故障排除

Linting 命令未找到

问题: 命令失败，提示 "command not found"

解决方案: 安装依赖项：

pnpm install

报告问题过多

问题： 代码检查报告了您未更改的文件中的问题

解决方案： 请确保您使用的是针对特定分支的命令：

# 推荐 - 仅检查您的更改
pnpm run lint:changes:branch:php

# 避免 - 检查整个代码库
pnpm run lint:php

自动修复后的冲突

问题: 运行 lint:php:fix 后出现 Git 冲突

解决方案:

1. 检查自动修复的内容: git diff
2. 如果修复不正确，请还原: git checkout -- path/to/file.php
3. 手动处理这些问题

注意事项

• 代码质量工具帮助在整个代码库中保持一致性
• 自动修复节省时间，但应始终进行审查
• 某些问题需要手动干预和对上下文的理解
• 提交前必须进行代码检查，以确保符合代码质量标准