code-review-web

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Review for Web

Web应用代码审查

Review and debug web application code with a focus on the patterns that actually break production. Stack-agnostic principles in SKILL.md. Stack-specific patterns in references.

针对Web应用代码进行审查和调试，重点关注实际会导致生产环境故障的模式。与技术栈无关的原则见SKILL.md，特定技术栈的模式见参考文件。

When to use

使用场景

Reviewing a pull request before merging
Debugging a production issue
Investigating a build failure
Auditing security or performance of existing code
Investigating environment variable or configuration issues
Triaging a "the site is broken" report

合并前审查拉取请求（PR）
调试生产环境问题
排查构建失败问题
审计现有代码的安全性或性能
排查环境变量或配置问题
处理“网站崩溃”的反馈

When NOT to use

非适用场景

Writing a new feature spec (use
```
pm-spec-writing
```
)
Pre-launch QA against the running site (use
```
qa-testing
```
)
Performance deep-dive on Core Web Vitals (use
```
performance-optimization
```
)
Deep accessibility compliance review (use
```
accessibility-audit
```
)

编写新功能规格说明书（使用
```
pm-spec-writing
```
）
针对运行中的网站进行上线前QA测试（使用
```
qa-testing
```
）
对Core Web Vitals进行深度性能分析（使用
```
performance-optimization
```
）
深度无障碍合规审查（使用
```
accessibility-audit
```
）

Required inputs

必要输入

The code, PR, error message, or symptom under review
Access to logs (build logs, function logs, server logs) if debugging
The stack (framework, hosting, database) - even at high level

If just a symptom is provided ("the site is broken"), the workflow's first step is gathering enough context to investigate.

待审查的代码、PR、错误信息或故障症状
调试时需要访问日志（构建日志、函数日志、服务器日志）
技术栈信息（框架、托管服务、数据库）——即使是大致信息也可

如果仅提供故障症状（如“网站崩溃”），工作流程的第一步是收集足够的上下文信息以开展排查。

The framework: 5 review dimensions

审查框架：5个审查维度

Every code review covers five dimensions. Pick the depth based on the situation.

每一次代码审查都涵盖这五个维度。根据实际情况选择审查深度。

1. Correctness

1. 正确性

Does the code do what it claims to do?

Logic matches the intent stated in the spec or PR description
Edge cases handled (empty states, error states, network failures)
Off-by-one errors, null/undefined handling, async race conditions
Tests exist for the change, or there's a reason they don't
The change does not break existing functionality (regression risk)

代码是否实现了其所宣称的功能？

逻辑与规格说明书或PR描述中声明的意图一致
处理了边缘情况（空状态、错误状态、网络故障）
检查是否存在差一错误、空值/未定义值处理问题、异步竞态条件
针对变更存在测试用例，或有合理理由无需测试
变更不会破坏现有功能（无回归风险）

2. Security

2. 安全性

Does the code expose anything sensitive or open an attack surface?

Secrets handling. No secrets, API keys, or service-role credentials in client-side code or version control
Auth checks. Every mutation endpoint validates the caller before acting
Input validation. User input sanitized before use in queries, file paths, or HTML
External requests. Outbound URLs validated; no SSRF on user-controlled inputs
CSRF protection. State-changing requests require a token or same-origin policy
Rate limiting. Public-facing mutation endpoints have rate limits
HTTPS-only. No HTTP in production code paths
Cookies. Session cookies have
```
Secure
```
,
```
HttpOnly
```
,
```
SameSite
```
attributes set
Environment variables. Server-only secrets are not prefixed with anything that exposes them to the client bundle

代码是否暴露了敏感信息或存在攻击面？

敏感信息处理：客户端代码或版本控制系统中不得包含密钥、API密钥或服务角色凭证
身份验证检查：每个变更端点在执行操作前都要验证调用者身份
输入验证：用户输入在用于查询、文件路径或HTML前需经过清理
外部请求：出站URL需验证；用户可控输入不会导致SSRF（服务器端请求伪造）
CSRF防护：状态变更请求需要令牌或同源策略保护
速率限制：面向公众的变更端点需设置速率限制
仅使用HTTPS：生产环境代码路径中不得使用HTTP
Cookie设置：会话Cookie需设置
```
Secure
```
、
```
HttpOnly
```
、
```
SameSite
```
属性
环境变量：仅服务器端可用的密钥不得使用会将其暴露给客户端包的前缀

3. Performance

3. 性能

Will this code scale and stay fast?

Database queries. No N+1 patterns. Joins or batch fetches preferred over loops with queries.
Pagination. Large result sets paginated, never loaded entirely.
Caching. Appropriate cache strategy for the data freshness needs.
Bundle size. Client-side dependencies justified. Tree-shaking working.
Image handling. Modern formats, lazy loading, explicit dimensions.
Background work. Slow operations moved off the request path.
Cold start sensitivity. Cold paths optimized if frequently triggered.

代码是否具备可扩展性并保持高效？

数据库查询：不存在N+1查询模式。优先使用连接查询或批量获取，而非循环内查询
分页处理：大型结果集需分页，不得一次性全部加载
缓存策略：根据数据新鲜度需求选择合适的缓存策略
包体积：客户端依赖的引入需合理。Tree-shaking（摇树优化）功能正常工作
图片处理：使用现代格式、懒加载，并明确指定尺寸
后台处理：将慢速操作移出请求处理路径
冷启动优化：若冷路径频繁触发，需进行优化

4. Reliability

4. 可靠性

What happens when this fails?

Error handling. Caught and handled, not swallowed. Errors logged with context.
Retries. Network calls have retry logic for transient failures.
Timeouts. External calls have explicit timeouts (no infinite waits).
Graceful degradation. Failure of non-critical paths does not crash the page.
Idempotency. Mutations that might be retried are safe to retry.
Logging. Enough context in logs to diagnose without reproducing.

当代码出现故障时会发生什么？

错误处理：错误被捕获并处理，而非被忽略。错误日志需包含上下文信息
重试机制：网络调用针对瞬时故障需具备重试逻辑
超时设置：外部调用需明确设置超时时间（无无限等待）
优雅降级：非关键路径故障不会导致页面崩溃
幂等性：可能被重试的变更操作需具备幂等性
日志记录：日志中包含足够上下文信息，无需重现即可诊断问题

5. Maintainability

5. 可维护性

Will the next person (or future you) understand this in six months?

Naming. Functions and variables named for what they do, not how.
Comments. Explain why, not what. The code says what.
Complexity. Functions do one thing. If a function takes 200 lines, it's doing too much.
Duplication. Same logic in multiple places gets extracted.
Dependencies. New dependencies justified. Each one is a maintenance burden.
Magic values. No literal
```
60000
```
in code. Use named constants.

六个月后，其他人（或未来的你）是否能理解这段代码？

命名规范：函数和变量的命名应体现其功能，而非实现方式
注释原则：注释应解释原因，而非内容。代码本身应说明做了什么
复杂度控制：函数应单一职责。若函数超过200行，则承担了过多职责
代码复用：多处重复的逻辑需提取为公共代码
依赖管理：引入新依赖需合理。每个依赖都是一项维护负担
魔法值处理：代码中不得使用字面量（如
```
60000
```
），应使用命名常量

Common bug patterns (stack-agnostic)

常见bug模式（与技术栈无关）

Patterns that recur across stacks and are worth checking on every review.

这些模式在不同技术栈中反复出现，每次审查都值得检查。

Build and deploy

构建与部署

Build-time data fetches that timeout. Routes that query a database during static generation can fail at scale. Mark them as runtime-rendered if the data must be fresh.
Environment variables not propagating. A var that works locally but breaks in production usually means it was not added to the production environment.
Mismatched env between preview and production. Deploys that work in preview but break on the production domain often have stack-specific URLs hardcoded.

构建时数据获取超时：静态生成期间查询数据库的路由在大规模场景下可能失败。若数据必须保持新鲜，需将其标记为运行时渲染
环境变量未同步：在本地正常工作但在生产环境失效的变量，通常意味着该变量未添加到生产环境配置中
预览环境与生产环境配置不匹配：在预览环境正常部署但在生产域名下崩溃的情况，通常是因为硬编码了特定技术栈的URL

URL and domain issues

URL与域名问题

Canonical pointing at staging or preview URL. Caused by client-exposed environment variables that pick up the wrong domain. Canonical domain should come from a server-only environment variable.
API URL pointing at the main domain that loops back. After a DNS cutover, the main domain may now serve a different application. APIs should live on dedicated subdomains.
HTTPS upgrade issues. Mixed content (HTTP resources loaded into HTTPS pages) breaks browsers' security model.

规范URL指向 staging 或预览URL：原因是客户端暴露的环境变量获取了错误的域名。规范域名应来自仅服务器端可用的环境变量
API URL指向主域名导致循环调用：DNS切换后，主域名可能现在服务于另一个应用。API应部署在专用子域名上
HTTPS升级问题：混合内容（HTTPS页面中加载HTTP资源）会破坏浏览器的安全模型

Cache invalidation

缓存失效

Stale content after deploy. Either the cache was not invalidated, or the invalidation requires a manual trigger that did not run.
CDN serving old asset under same filename. Always use a new filename or cache-bust query string when replacing assets.
Cache headers too aggressive. Long max-age on resources that change frequently leads to users seeing stale content for hours or days.

部署后内容陈旧：要么缓存未失效，要么失效操作需要手动触发但未执行
CDN使用相同文件名提供旧资源：替换资源时应始终使用新文件名或缓存破击查询字符串
缓存头设置过于激进：频繁变更的资源设置过长的max-age会导致用户在数小时或数天内看到陈旧内容

Database and data

数据库与数据

N+1 queries. Loop with a query inside the loop. Replace with batch fetch or join.
Missing limits on table scans. Forgetting
```
LIMIT
```
on queries that hit large tables.
Connection pool exhaustion. Too many concurrent connections, often from build-time fetches in parallel routes.
Schema migration without backfill. Adding a NOT NULL column without populating it for existing rows.

N+1查询：循环内包含查询操作。应替换为批量获取或连接查询
表扫描未设置限制：针对大型表的查询忘记添加
```
LIMIT
```
连接池耗尽：并发连接过多，通常源于并行路由中的构建时数据获取
模式迁移未回填数据：添加NOT NULL列但未为现有行填充数据

Image handling

图片处理

Image not loading after upload. CDN cached the previous filename. Use new filenames for replacements.
Layout shift from images. Missing width/height attributes. Always specify both.
Slow LCP from large images. Hero images not optimized for size or format.

上传后图片无法加载：CDN缓存了旧文件名。替换图片时应使用新文件名
图片导致布局偏移：缺少width/height属性。应始终同时指定两者
大图片导致LCP缓慢：首屏英雄图片未针对尺寸或格式进行优化

External integrations

外部集成

Bot mitigation blocking server-to-server calls. CDN or firewall is challenging legitimate automated traffic. Whitelist server IPs or disable challenges for API endpoints.
API rate limit triggered in production. Worked locally where traffic was tiny. Add backoff and rate limiting awareness.

机器人防护拦截服务器间调用：CDN或防火墙拦截了合法的自动化流量。应将服务器IP加入白名单，或为API端点禁用防护验证
生产环境触发API速率限制：在本地流量较小时正常工作。需添加退避机制并实现速率限制感知

Security

安全性

Unprotected revalidation or admin endpoints. Always require a secret token.
PII in URLs. Visible in server logs, browser history, referrer headers.
Secrets exposed in client bundle. Anything that gets sent to the browser is public.

重新验证或管理端点未受保护：始终需要密钥令牌验证
URL中包含个人可识别信息（PII）：这些信息会出现在服务器日志、浏览器历史记录和Referrer头中
客户端包中暴露敏感信息：任何发送到浏览器的内容都是公开的

Workflow

工作流程

Gather context. What stack? What's broken or under review? Logs available?
Pick the depth. Quick scan for a small PR. Full review for a major change. Deep dive for a production incident.
Run through the 5 dimensions. Note issues by severity (blocker, important, minor).
Check stack-specific patterns. Reference the appropriate stack guide.
For incidents: identify the smallest hypothesis-driven fix. Reproduce locally if possible.
Write the review. Use the template in
```
references/review-template.md
```
for formal reviews.

收集上下文：使用的技术栈是什么？故障点或待审查内容是什么？是否有日志可用？
选择审查深度：小型PR进行快速扫描；重大变更进行全面审查；生产事件进行深度排查
覆盖5个审查维度：按严重程度（阻塞、重要、次要）记录问题
检查特定技术栈模式：参考对应的技术栈指南
针对事件：确定基于假设的最小修复方案。尽可能在本地重现问题
撰写审查报告：正式审查使用
```
references/review-template.md
```
中的模板

Failure patterns

错误审查模式

"Looks good to me" on a 500-line PR. If the review takes 5 minutes on a large PR, the review didn't happen.
Reviewing without running the code. Some bugs only surface at runtime. Pull the branch and run it.
Over-indexing on style. Bikeshedding on formatting while missing logic bugs.
Skipping security review on "internal" features. Internal becomes external faster than expected.
Treating warnings as decoration. Build warnings often become production errors after a dependency update.
Debugging without reading the full error message. First line of the stack trace is often not the actual cause. Read all of it.

对500行的PR仅回复“看起来没问题”：如果大型PR的审查仅耗时5分钟，相当于没有进行审查
未运行代码就进行审查：有些bug仅在运行时才会显现。应拉取分支并运行代码
过度关注代码风格：纠结于格式细节却忽略了逻辑bug
跳过“内部”功能的安全审查：内部功能转为外部功能的速度比预期更快
将警告视为无关紧要：依赖更新后，构建警告通常会变成生产环境错误
未完整阅读错误信息就调试：堆栈跟踪的第一行通常不是实际原因。应完整阅读所有内容

Debugging workflow

调试工作流程

When a production issue is reported:

Read the full error message. Including the stack trace.
Check hosting build and function logs. The exact failing line is usually here.
Identify the last working version.
```
git log --oneline
```
and check recent commits.
Reproduce locally. Confirms it's a code issue and not an environment issue.
Check environment variables. Especially after deploys or DNS changes.
Check cache state. Force a cache invalidation before concluding it's a code bug.
Make the minimal fix. Big refactors during incidents create more incidents.
Verify in production. Check the actual fix worked, not just that the deploy succeeded.
Document. What was the root cause? What would have prevented it? File the learnings.

当收到生产环境问题反馈时：

完整阅读错误信息：包括堆栈跟踪
检查托管服务的构建日志和函数日志：通常可以找到确切的故障代码行
确定最后正常运行的版本：使用
```
git log --oneline
```
查看最近的提交记录
在本地重现问题：确认是代码问题而非环境问题
检查环境变量：尤其是在部署或DNS变更后
检查缓存状态：在判定为代码bug前，先强制使缓存失效
进行最小化修复：事件处理期间进行大规模重构会引发更多问题
在生产环境验证：确认修复实际生效，而非仅确认部署成功
记录文档：记录根本原因是什么？如何预防？将经验教训整理归档

Output format

输出格式

For PR reviews: comments inline on the PR, plus a summary if needed.

For formal code reviews: a markdown document at

code-review-[date].md

with:

Scope (what was reviewed)
Summary (overall assessment)
Critical issues (blockers)
Important issues
Minor issues
Suggestions for follow-up

For incidents: a postmortem document. See

after-action-report

for that format.

PR审查：在PR中添加内联评论，必要时附上总结。

正式代码审查：生成名为

code-review-[date].md

的Markdown文档，包含以下内容：

范围（审查内容）
总结（整体评估）
关键问题（阻塞项）
重要问题
次要问题
后续改进建议

事件处理：生成事后分析文档。格式参考

after-action-report

。

Reference files

参考文件

```
references/review-template.md
```
- Markdown template for formal code reviews.
```
references/nextjs-patterns.md
```
- Stack-specific patterns for Next.js (App Router, ISR, Server Components, common bugs).
```
references/wordpress-headless-patterns.md
```
- Stack-specific patterns for headless WordPress integrations.

```
references/review-template.md
```
- 正式代码审查的Markdown模板
```
references/nextjs-patterns.md
```
- Next.js特定技术栈模式（App Router、ISR、Server Components、常见bug）
```
references/wordpress-headless-patterns.md
```
- 无头WordPress集成的特定技术栈模式