Web开发最佳实践指南：Lighthouse安全、兼容性与代码质量优化

best-practices by tech-leads-club/agent-skills

72 周安装量

1,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/tech-leads-club/agent-skills --skill best-practices

开发网站优化安全

🇨🇳中文介绍

最佳实践

基于 Lighthouse 最佳实践审计的现代 Web 开发标准。涵盖安全性、浏览器兼容性和代码质量模式。

安全性

全面使用 HTTPS

强制使用 HTTPS：

<!-- ❌ 混合内容 -->
<img src="http://example.com/image.jpg" />
<script src="http://cdn.example.com/script.js"></script>

<!-- ✅ 仅使用 HTTPS -->
<img src="https://example.com/image.jpg" />
<script src="https://cdn.example.com/script.js"></script>

<!-- ✅ 协议相对（将使用页面的协议） -->
<img src="//example.com/image.jpg" />

HSTS 标头：

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

内容安全策略 (CSP)

<!-- 通过 meta 标签设置基本 CSP -->
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; 
               script-src 'self' https://trusted-cdn.com; 
               style-src 'self' 'unsafe-inline';
               img-src 'self' data: https:;
               connect-src 'self' https://api.example.com;"
/>

<!-- 更好的方式：HTTP 标头 -->

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

Viewport meta 标签

<!-- ❌ 缺少 viewport -->
<head>
  <title>Page</title>
</head>

<!-- ✅ 响应式 viewport -->
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page</title>
</head>

// ❌ 浏览器检测（脆弱）
if (navigator.userAgent.includes('Chrome')) {
  // Chrome 特定代码
}

// ✅ 特性检测
if ('IntersectionObserver' in window) {
  // 使用 IntersectionObserver
} else {
  // 回退方案
}

// ✅ 在 CSS 中使用 @supports
@supports (display: grid) {
  .container {
    display: grid;
  }
}

@supports not (display: grid) {
  .container {
    display: flex;
  }
}

填充工具（需要时）

<!-- 有条件地加载填充工具 -->
<script>
  if (!('fetch' in window)) {
    document.write('<script src="/polyfills/fetch.js"><\/script>')
  }
</script>

<!-- 或使用 polyfill.io -->
<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,IntersectionObserver"></script>

// ❌ document.write（阻塞解析）
document.write('<script src="..."></script>');

// ✅ 动态脚本加载
const script = document.createElement('script');
script.src = '...';
document.head.appendChild(script);

// ❌ 同步 XHR（阻塞主线程）
const xhr = new XMLHttpRequest();
xhr.open('GET', url, false); // false = 同步

// ✅ 异步 fetch
const response = await fetch(url);

// ❌ Application Cache（已弃用）
<html manifest="cache.manifest">

// ✅ Service Workers
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

事件监听器被动模式

// ❌ 非被动的触摸/滚轮监听器（可能阻塞滚动）
element.addEventListener('touchstart', handler)
element.addEventListener('wheel', handler)

// ✅ 被动监听器（允许平滑滚动）
element.addEventListener('touchstart', handler, { passive: true })
element.addEventListener('wheel', handler, { passive: true })

// ✅ 如果需要 preventDefault，请明确声明
element.addEventListener('touchstart', handler, { passive: false })

// ❌ 生产环境中的错误
console.log('Debug info') // 在生产环境中移除
throw new Error('Unhandled') // 捕获所有错误

// ✅ 正确的错误处理
try {
  riskyOperation()
} catch (error) {
  // 记录到错误跟踪服务
  errorTracker.captureException(error)
  // 显示用户友好的消息
  showErrorMessage('Something went wrong. Please try again.')
}

错误边界 (React)

class ErrorBoundary extends React.Component {
  state = { hasError: false }

  static getDerivedStateFromError(error) {
    return { hasError: true }
  }

  componentDidCatch(error, info) {
    errorTracker.captureException(error, { extra: info })
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI />
    }
    return this.props.children
  }
}

// 用法
;<ErrorBoundary>
  <App />
</ErrorBoundary>

全局错误处理器

// 捕获未处理的错误
window.addEventListener('error', (event) => {
  errorTracker.captureException(event.error)
})

// 捕获未处理的 Promise 拒绝
window.addEventListener('unhandledrejection', (event) => {
  errorTracker.captureException(event.reason)
})

// ❌ 生产环境中暴露源映射
// webpack.config.js
module.exports = {
  devtool: 'source-map', // 暴露源代码
}

// ✅ 隐藏的源映射（上传到错误跟踪器）
module.exports = {
  devtool: 'hidden-source-map',
}

// ✅ 或者生产环境中不使用源映射
module.exports = {
  devtool: process.env.NODE_ENV === 'production' ? false : 'source-map',
}

// ❌ 阻塞脚本
<script src="heavy-library.js"></script>

// ✅ 延迟脚本
<script defer src="heavy-library.js"></script>

// ❌ 阻塞的 CSS 导入
@import url('other-styles.css');

// ✅ Link 标签（并行加载）
<link rel="stylesheet" href="styles.css">
<link rel="stylesheet" href="other-styles.css">

高效的事件处理器

// ❌ 每个元素上都绑定处理器
items.forEach((item) => {
  item.addEventListener('click', handleClick)
})

// ✅ 事件委托
container.addEventListener('click', (e) => {
  if (e.target.matches('.item')) {
    handleClick(e)
  }
})

// ❌ 内存泄漏（从未移除）
const handler = () => {
  /* ... */
}
window.addEventListener('resize', handler)

// ✅ 完成后清理
const handler = () => {
  /* ... */
}
window.addEventListener('resize', handler)

// 稍后，当组件卸载时：
window.removeEventListener('resize', handler)

// ✅ 使用 AbortController
const controller = new AbortController()
window.addEventListener('resize', handler, { signal: controller.signal })

// 清理：
controller.abort()

<!-- ❌ 无效的 HTML -->
<div id="header">
  <div id="header">
    <!-- 重复的 ID -->

    <ul>
      <div>Item</div>
      <!-- 无效的子元素 -->
    </ul>

    <a href="/"><button>Click</button></a>
    <!-- 无效的嵌套 -->

    <!-- ✅ 有效的 HTML -->
    <header id="site-header"></header>

    <ul>
      <li>Item</li>
    </ul>

    <a href="/" class="button">Click</a>
  </div>
</div>

<!-- ❌ 非语义化 -->
<div class="header">
  <div class="nav">
    <div class="nav-item">Home</div>
  </div>
</div>
<div class="main">
  <div class="article">
    <div class="title">Headline</div>
  </div>
</div>

<!-- ✅ 语义化 HTML5 -->
<header>
  <nav>
    <a href="/">Home</a>
  </nav>
</header>
<main>
  <article>
    <h1>Headline</h1>
  </article>
</main>

<!-- ❌ 扭曲的图像 -->
<img src="photo.jpg" width="300" height="100" />
<!-- 如果实际比例是 4:3，这会挤压图像 -->

<!-- ✅ 保持宽高比 -->
<img src="photo.jpg" width="300" height="225" />
<!-- 实际的 4:3 尺寸 -->

<!-- ✅ 使用 CSS object-fit 以获得灵活性 -->
<img src="photo.jpg" style="width: 300px; height: 200px; object-fit: cover;" />

// ❌ 在页面加载时请求（用户体验差，通常被拒绝）
navigator.geolocation.getCurrentPosition(success, error)

// ✅ 在上下文中，用户操作后请求
findNearbyButton.addEventListener('click', async () => {
  // 解释为什么需要它
  if (await showPermissionExplanation()) {
    navigator.geolocation.getCurrentPosition(success, error)
  }
})

<!-- 限制强大功能 -->
<meta http-equiv="Permissions-Policy" content="geolocation=(), camera=(), microphone=()" />

<!-- 或允许特定来源 -->
<meta http-equiv="Permissions-Policy" content="geolocation=(self 'https://maps.example.com')" />

安全性（关键）

启用 HTTPS，无混合内容
无易受攻击的依赖项 (npm audit)
配置了 CSP 标头
存在安全标头
无暴露的源映射

有效的 HTML5 doctype
字符集在 head 中首先声明
存在 viewport meta 标签
未使用已弃用的 API
滚动/触摸使用被动事件监听器

无控制台错误
有效的 HTML（无重复 ID）
使用语义化 HTML 元素
正确的错误处理
组件中进行内存清理

无侵入性插页式广告
在上下文中请求权限
清晰的错误消息
适当的图像宽高比

工具	用途
`npm audit`	依赖项漏洞
SecurityHeaders.com	标头分析
W3C Validator	HTML 验证
Lighthouse	最佳实践审计
Observatory	安全扫描

🇺🇸English

Best practices

Modern web development standards based on Lighthouse best practices audits. Covers security, browser compatibility, and code quality patterns.

Security

HTTPS everywhere

Enforce HTTPS:

<!-- ❌ Mixed content -->
<img src="http://example.com/image.jpg" />
<script src="http://cdn.example.com/script.js"></script>

<!-- ✅ HTTPS only -->
<img src="https://example.com/image.jpg" />
<script src="https://cdn.example.com/script.js"></script>

<!-- ✅ Protocol-relative (will use page's protocol) -->
<img src="//example.com/image.jpg" />

HSTS Header:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Content Security Policy (CSP)

<!-- Basic CSP via meta tag -->
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; 
               script-src 'self' https://trusted-cdn.com; 
               style-src 'self' 'unsafe-inline';
               img-src 'self' data: https:;
               connect-src 'self' https://api.example.com;"
/>

<!-- Better: HTTP header -->

CSP Header (recommended):

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-abc123' https://trusted.com;
  style-src 'self' 'nonce-abc123';
  img-src 'self' data: https:;
  connect-src 'self' https://api.example.com;
  frame-ancestors 'self';
  base-uri 'self';
  form-action 'self';

Using nonces for inline scripts:

<script nonce="abc123">
  // This inline script is allowed
</script>

Security headers

# Prevent clickjacking
X-Frame-Options: DENY

# Prevent MIME type sniffing
X-Content-Type-Options: nosniff

# Enable XSS filter (legacy browsers)
X-XSS-Protection: 1; mode=block

# Control referrer information
Referrer-Policy: strict-origin-when-cross-origin

# Permissions policy (formerly Feature-Policy)
Permissions-Policy: geolocation=(), microphone=(), camera=()

No vulnerable libraries

# Check for vulnerabilities
npm audit
yarn audit

# Auto-fix when possible
npm audit fix

# Check specific package
npm ls lodash

Keep dependencies updated:

// package.json
{
  "scripts": {
    "audit": "npm audit --audit-level=moderate",
    "update": "npm update && npm audit fix"
  }
}

Known vulnerable patterns to avoid:

// ❌ Prototype pollution vulnerable patterns
Object.assign(target, userInput)
_.merge(target, userInput)

// ✅ Safer alternatives
const safeData = JSON.parse(JSON.stringify(userInput))

Input sanitization

// ❌ XSS vulnerable
element.innerHTML = userInput
document.write(userInput)

// ✅ Safe text content
element.textContent = userInput

// ✅ If HTML needed, sanitize
import DOMPurify from 'dompurify'
element.innerHTML = DOMPurify.sanitize(userInput)

Secure cookies

// ❌ Insecure cookie
document.cookie = "session=abc123";

// ✅ Secure cookie (server-side)
Set-Cookie: session=abc123; Secure; HttpOnly; SameSite=Strict; Path=/

Browser compatibility

Doctype declaration

<!-- ❌ Missing or invalid doctype -->
<html>
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">

  <!-- ✅ HTML5 doctype -->
  <!DOCTYPE html>
  <html lang="en"></html>
</html>

Character encoding

<!-- ❌ Missing or late charset -->
<html>
  <head>
    <title>Page</title>
    <meta charset="UTF-8" />
  </head>

  <!-- ✅ Charset as first element in head -->
  <html>
    <head>
      <meta charset="UTF-8" />
      <title>Page</title>
    </head>
  </html>
</html>

Viewport meta tag

<!-- ❌ Missing viewport -->
<head>
  <title>Page</title>
</head>

<!-- ✅ Responsive viewport -->
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page</title>
</head>

Feature detection

// ❌ Browser detection (brittle)
if (navigator.userAgent.includes('Chrome')) {
  // Chrome-specific code
}

// ✅ Feature detection
if ('IntersectionObserver' in window) {
  // Use IntersectionObserver
} else {
  // Fallback
}

// ✅ Using @supports in CSS
@supports (display: grid) {
  .container {
    display: grid;
  }
}

@supports not (display: grid) {
  .container {
    display: flex;
  }
}

Polyfills (when needed)

<!-- Load polyfills conditionally -->
<script>
  if (!('fetch' in window)) {
    document.write('<script src="/polyfills/fetch.js"><\/script>')
  }
</script>

<!-- Or use polyfill.io -->
<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,IntersectionObserver"></script>

Deprecated APIs

Avoid these

// ❌ document.write (blocks parsing)
document.write('<script src="..."></script>');

// ✅ Dynamic script loading
const script = document.createElement('script');
script.src = '...';
document.head.appendChild(script);

// ❌ Synchronous XHR (blocks main thread)
const xhr = new XMLHttpRequest();
xhr.open('GET', url, false); // false = synchronous

// ✅ Async fetch
const response = await fetch(url);

// ❌ Application Cache (deprecated)
<html manifest="cache.manifest">

// ✅ Service Workers
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

Event listener passive

// ❌ Non-passive touch/wheel (may block scrolling)
element.addEventListener('touchstart', handler)
element.addEventListener('wheel', handler)

// ✅ Passive listeners (allows smooth scrolling)
element.addEventListener('touchstart', handler, { passive: true })
element.addEventListener('wheel', handler, { passive: true })

// ✅ If you need preventDefault, be explicit
element.addEventListener('touchstart', handler, { passive: false })

Console & errors

No console errors

// ❌ Errors in production
console.log('Debug info') // Remove in production
throw new Error('Unhandled') // Catch all errors

// ✅ Proper error handling
try {
  riskyOperation()
} catch (error) {
  // Log to error tracking service
  errorTracker.captureException(error)
  // Show user-friendly message
  showErrorMessage('Something went wrong. Please try again.')
}

Error boundaries (React)

class ErrorBoundary extends React.Component {
  state = { hasError: false }

  static getDerivedStateFromError(error) {
    return { hasError: true }
  }

  componentDidCatch(error, info) {
    errorTracker.captureException(error, { extra: info })
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI />
    }
    return this.props.children
  }
}

// Usage
;<ErrorBoundary>
  <App />
</ErrorBoundary>

Global error handler

// Catch unhandled errors
window.addEventListener('error', (event) => {
  errorTracker.captureException(event.error)
})

// Catch unhandled promise rejections
window.addEventListener('unhandledrejection', (event) => {
  errorTracker.captureException(event.reason)
})

Source maps

Production configuration

// ❌ Source maps exposed in production
// webpack.config.js
module.exports = {
  devtool: 'source-map', // Exposes source code
}

// ✅ Hidden source maps (uploaded to error tracker)
module.exports = {
  devtool: 'hidden-source-map',
}

// ✅ Or no source maps in production
module.exports = {
  devtool: process.env.NODE_ENV === 'production' ? false : 'source-map',
}

Performance best practices

Avoid blocking patterns

// ❌ Blocking script
<script src="heavy-library.js"></script>

// ✅ Deferred script
<script defer src="heavy-library.js"></script>

// ❌ Blocking CSS import
@import url('other-styles.css');

// ✅ Link tags (parallel loading)
<link rel="stylesheet" href="styles.css">
<link rel="stylesheet" href="other-styles.css">

Efficient event handlers

// ❌ Handler on every element
items.forEach((item) => {
  item.addEventListener('click', handleClick)
})

// ✅ Event delegation
container.addEventListener('click', (e) => {
  if (e.target.matches('.item')) {
    handleClick(e)
  }
})

Memory management

// ❌ Memory leak (never removed)
const handler = () => {
  /* ... */
}
window.addEventListener('resize', handler)

// ✅ Cleanup when done
const handler = () => {
  /* ... */
}
window.addEventListener('resize', handler)

// Later, when component unmounts:
window.removeEventListener('resize', handler)

// ✅ Using AbortController
const controller = new AbortController()
window.addEventListener('resize', handler, { signal: controller.signal })

// Cleanup:
controller.abort()

Code quality

Valid HTML

<!-- ❌ Invalid HTML -->
<div id="header">
  <div id="header">
    <!-- Duplicate ID -->

    <ul>
      <div>Item</div>
      <!-- Invalid child -->
    </ul>

    <a href="/"><button>Click</button></a>
    <!-- Invalid nesting -->

    <!-- ✅ Valid HTML -->
    <header id="site-header"></header>

    <ul>
      <li>Item</li>
    </ul>

    <a href="/" class="button">Click</a>
  </div>
</div>

Semantic HTML

<!-- ❌ Non-semantic -->
<div class="header">
  <div class="nav">
    <div class="nav-item">Home</div>
  </div>
</div>
<div class="main">
  <div class="article">
    <div class="title">Headline</div>
  </div>
</div>

<!-- ✅ Semantic HTML5 -->
<header>
  <nav>
    <a href="/">Home</a>
  </nav>
</header>
<main>
  <article>
    <h1>Headline</h1>
  </article>
</main>

Image aspect ratios

<!-- ❌ Distorted images -->
<img src="photo.jpg" width="300" height="100" />
<!-- If actual ratio is 4:3, this squishes the image -->

<!-- ✅ Preserve aspect ratio -->
<img src="photo.jpg" width="300" height="225" />
<!-- Actual 4:3 dimensions -->

<!-- ✅ CSS object-fit for flexibility -->
<img src="photo.jpg" style="width: 300px; height: 200px; object-fit: cover;" />

Permissions & privacy

Request permissions properly

// ❌ Request on page load (bad UX, often denied)
navigator.geolocation.getCurrentPosition(success, error)

// ✅ Request in context, after user action
findNearbyButton.addEventListener('click', async () => {
  // Explain why you need it
  if (await showPermissionExplanation()) {
    navigator.geolocation.getCurrentPosition(success, error)
  }
})

Permissions policy

<!-- Restrict powerful features -->
<meta http-equiv="Permissions-Policy" content="geolocation=(), camera=(), microphone=()" />

<!-- Or allow for specific origins -->
<meta http-equiv="Permissions-Policy" content="geolocation=(self 'https://maps.example.com')" />

Audit checklist

Security (critical)

HTTPS enabled, no mixed content
No vulnerable dependencies (npm audit)
CSP headers configured
Security headers present
No exposed source maps

Compatibility

Valid HTML5 doctype
Charset declared first in head
Viewport meta tag present
No deprecated APIs used
Passive event listeners for scroll/touch

Code quality

No console errors
Valid HTML (no duplicate IDs)
Semantic HTML elements used
Proper error handling
Memory cleanup in components

UX

No intrusive interstitials
Permission requests in context
Clear error messages
Appropriate image aspect ratios

Tools

Tool	Purpose
`npm audit`	Dependency vulnerabilities
SecurityHeaders.com	Header analysis
W3C Validator	HTML validation
Lighthouse	Best practices audit
Observatory	Security scan

References

Weekly Installs

Repository

tech-leads-club…t-skills

GitHub Stars

1.9K

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode68

gemini-cli66

codex66

github-copilot66

kimi-cli64

amp63

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

142,000 周安装

Web开发最佳实践指南：Lighthouse安全、兼容性与代码质量优化

🇨🇳中文介绍

最佳实践

安全性

全面使用 HTTPS

内容安全策略 (CSP)

相关 Skills

安全标头

无漏洞库

输入清理

安全 Cookie

浏览器兼容性

文档类型声明

字符编码

Viewport meta 标签

特性检测

填充工具（需要时）

已弃用的 API

避免使用这些

事件监听器被动模式

控制台与错误

无控制台错误

错误边界 (React)

全局错误处理器

源映射

生产环境配置

性能最佳实践

避免阻塞模式

高效的事件处理器

内存管理

代码质量

有效的 HTML

语义化 HTML

图像宽高比

权限与隐私

正确请求权限

权限策略

审计清单

安全性（关键）

兼容性

代码质量

用户体验

工具

参考资料

🇺🇸English

Best practices

Security

HTTPS everywhere

Content Security Policy (CSP)

Security headers

No vulnerable libraries

Input sanitization

Secure cookies

Browser compatibility

Doctype declaration

Character encoding

Viewport meta tag

Feature detection

Polyfills (when needed)

Deprecated APIs

Avoid these

Event listener passive

Console & errors

No console errors

Error boundaries (React)

Global error handler

Source maps

Production configuration

Performance best practices

Avoid blocking patterns

Efficient event handlers

Memory management

Code quality

Valid HTML

Semantic HTML

Image aspect ratios

Permissions & privacy

Request permissions properly

Permissions policy

Audit checklist